spring-boot-starter.md

Spring Boot Starter

The starter adds automatic MVC and WebFlux exception capture plus Spring-managed BugDNA services.

See Core vs Spring Boot starter for a feature-by-feature comparison, including which core types require application-defined beans.

Requirements

• Java 17 or newer
• Spring Boot 4.x
• Spring MVC or WebFlux for automatic web exception capture

Setup

<dependency>
    <groupId>io.github.arnabnandy7</groupId>
    <artifactId>bugdna-spring-boot-starter</artifactId>
    <version>1.1.2</version>
</dependency>

The starter is discovered through Spring Boot's AutoConfiguration.imports mechanism.

@EnableBugDna is available when explicit opt-in is preferred:

@EnableBugDna
@SpringBootApplication
class Application {
}

Automatic MVC Capture

When enabled in a servlet web application, BugDNA registers a HandlerExceptionResolver at highest precedence. It fingerprints and logs the exception, then returns null so Spring continues its normal resolution flow.

Default log shape:

ERROR [BUGDNA-7A3F21] Unhandled exception fingerprinted by bugdna

Stack traces are disabled by default and can be enabled with bugdna.include-stack-trace=true.

Automatic WebFlux Capture

In a reactive web application, BugDNA registers a highest-precedence WebExceptionHandler. It fingerprints and logs the exception, then re-emits the same failure so Spring WebFlux continues its normal error handling.

No controller or reactive-chain changes are required:

@RestController
class PaymentController {

    @GetMapping("/payments/{id}")
    Mono<Payment> payment(@PathVariable String id) {
        return paymentService.find(id);
    }
}

An unhandled error emitted by paymentService.find(id) is captured automatically. The same bugdna.log-enabled, bugdna.mdc-enabled, and bugdna.include-stack-trace properties apply to MVC and WebFlux.

Inject the Service

@Service
class FailureReporter {

    private final BugDnaSpringService bugDna;

    FailureReporter(BugDnaSpringService bugDna) {
        this.bugDna = bugDna;
    }

    Fingerprint capture(Throwable failure) {
        return bugDna.fingerprint(failure);
    }
}

The service records the fingerprint in the recent repository and shared FailureTracker. If OpenTelemetry is already active, the starter also enriches the current span with attributes such as bugdna=BUGDNA-7A3F21.

Operational context is also supported:

bugDna.fingerprint(
        exception,
        FailureContext.of(100, 10, false)
);

Background Job Example

Automatic web capture does not cover scheduled jobs, listeners, or manually created threads. Record those failures explicitly:

@Component
class PaymentReconciliationJob {
    private final BugDnaSpringService bugDna;

    PaymentReconciliationJob(BugDnaSpringService bugDna) {
        this.bugDna = bugDna;
    }

    @Scheduled(fixedDelayString = "PT10M")
    void reconcile() {
        try {
            reconcilePayments();
        } catch (RuntimeException failure) {
            Fingerprint fingerprint = bugDna.fingerprint(failure);
            log.error("Reconciliation failed [{}]", fingerprint.getId(), failure);
        }
    }
}

Inject the Tracker

@Component
class FailureReport {

    private final FailureTracker tracker;

    FailureReport(FailureTracker tracker) {
        this.tracker = tracker;
    }

    String topFailures() {
        return tracker.topFailureReport();
    }
}

Example result:

Top 10 Failure Signatures
BUGDNA-001
Count: 421
BUGDNA-002
Count: 53

Override Beans

Core starter beans use @ConditionalOnMissingBean. Applications may provide custom beans for FailureTracker, BugDnaSpringService, or BugDnaFingerprintRepository.

Disable Features

bugdna.enabled=false

Disable only automatic exception logging:

bugdna.log-enabled=false

Disable only OpenTelemetry span enrichment:

bugdna.otel-enabled=false

Keep automatic capture but suppress stack traces:

bugdna.log-enabled=true
bugdna.include-stack-trace=false

See Configuration for every property.