Observability¶

The Spring starter integrates with logs, SLF4J MDC, OpenTelemetry span enrichment, Actuator, Micrometer, and Prometheus.

Automatic Logs¶

Unhandled Spring MVC and WebFlux exceptions produce:

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

Set bugdna.include-stack-trace=true to include the exception.

MDC Fields¶

When bugdna.mdc-enabled=true, the following fields are present during the automatic BugDNA log call:

Key	Example
`bugdna`	`BUGDNA-7A3F21`
`bugdna.id`	`BUGDNA-7A3F21`
`bugdna.confidence`	`90`
`bugdna.category`	`DATABASE`
`bugdna.family`	`DATABASE_CONNECTIVITY`
`bugdna.priority`	`UNKNOWN`

BugDNA removes these keys in a finally block after logging. In WebFlux this MDC scope covers BugDNA's synchronous log call only; it is not propagated as Reactor context. BugDNA does not attach MDC to arbitrary core-library calls.

OpenTelemetry Span Enrichment¶

When io.opentelemetry:opentelemetry-api is on the classpath and bugdna.otel-enabled=true, BugDNA adds fingerprint attributes to the current OpenTelemetry span after generating a fingerprint. BugDNA does not create traces, export spans, or configure sampling.

For an existing trace such as:

traceId=abc

the active span receives:

Attribute	Example
`bugdna`	`BUGDNA-7A3F21`
`bugdna.id`	`BUGDNA-7A3F21`
`bugdna.confidence`	`90`
`bugdna.category`	`DATABASE`
`bugdna.family`	`DATABASE_CONNECTIVITY`
`bugdna.priority`	`UNKNOWN`

This lets teams query spans by failure fingerprint in their existing OpenTelemetry backend.

Actuator Endpoint¶

When Actuator is present, the starter registers the bugdna endpoint.

management.endpoints.web.exposure.include=health,bugdna

Query it locally:

curl http://localhost:8080/actuator/bugdna

Example response shape:

{
  "count": 1,
  "recent": [
    {
      "observedAt": "2026-06-12T00:00:00Z",
      "id": "BUGDNA-7A3F21",
      "rootCause": "java.lang.NullPointerException",
      "signature": "UserService#getUser",
      "stabilityScore": 90,
      "category": "UNKNOWN",
      "family": "UNKNOWN",
      "priority": "UNKNOWN"
    }
  ]
}

The endpoint is in-memory and bounded by bugdna.recent-limit.

Micrometer¶

When a MeterRegistry bean exists, BugDNA registers:

Meter	Meaning
`bugdna.failures.total`	Failures recorded by the starter since startup
`bugdna.unique.failures`	Distinct fingerprint IDs observed since startup

These are gauges backed by the starter repository's lifetime counters.

Prometheus¶

Add the Prometheus registry to the application and expose the endpoint:

management.endpoints.web.exposure.include=health,prometheus

Prometheus-normalized names:

bugdna_failures_total
bugdna_unique_failures

Metrics reset when the application restarts.

Example PromQL:

bugdna_unique_failures

delta(bugdna_failures_total[15m])

The first query shows currently known unique IDs. The second shows failure growth over 15 minutes when the process has not restarted during that range.

Core Applications¶

The core artifact has no logging or metrics dependency. Use Fingerprint and FailureTracker values with the observability system chosen by the application.