Turn recurring stack traces into deterministic fingerprints you can group, track, compare, and monitor.

The full article is available here.

Production logs are excellent at telling us that something failed. They are often less helpful at answering a more operational question:

Have we seen this exact failure before?

The same bug can appear thousands of times with different timestamps, request IDs, user IDs, exception messages, and line numbers. To a person reading the logs, those events may clearly represent one underlying problem. To a log pipeline, however, they are usually thousands of unrelated blocks of text.

I built BugDNA to give recurring Java failures a stable identity.

BugDNA converts an exception into a deterministic fingerprint, such as:

BUGDNA-7A3F21C98B64E12

Once a failure has an identity, it becomes much easier to count it, compare it between deployments, attach it to logs and metrics, detect bursts, and discuss it across engineering teams.

BugDNA is open source, released under the MIT License, and available as a core Java library, a Spring Boot starter, and a command-line log analyser.

The problem with grouping failures by message

A common first attempt at exception grouping is to use the exception class and message:

NullPointerException: customer 481 has no billing profile
NullPointerException: customer 927 has no billing profile

These messages are different, but the bug may be identical.

Line numbers create a similar problem. Adding a comment or moving a method can turn this:

PaymentService.java:142

into this:

PaymentService.java:147

The application behaviour did not necessarily change, but a line-based grouping key would say that it did.

BugDNA deliberately excludes volatile data from fingerprint identity:

• Exception messages
• Line numbers
• Timestamps
• Request IDs
• User identifiers

Instead, it uses the deepest exception type and up to five normalised stack frames. A normalised frame contains the class and method name, but not the source line.

Conceptually, the canonical input looks like this:

java.lang.NullPointerException
com.example.UserService#getUser
com.example.UserController#showUser

BugDNA hashes that canonical representation with SHA-256 and exposes the first 16 uppercase hexadecimal characters with a `BUGDNA-` prefix.

This means failures caused by different input values can still receive the same ID, while a meaningful refactor, such as renaming `getUser` to `loadUser`, can produce a new one.

That distinction is intentional: the goal is not to pretend that fingerprints
never change. The goal is to remove accidental variation while preserving useful structural changes.

Generating a fingerprint

The core library targets Java 8 and has no framework dependency.

Add it with Maven:

<dependency>
    <groupId>io.github.arnabnandy7</groupId>
    <artifactId>bugdna</artifactId>
    <version>1.0.1</version>
</dependency>

Then generate a fingerprint from any `Throwable`:

try {
    userRepository.findById(userId);
} catch (RuntimeException failure) {
    Fingerprint fingerprint = BugDna.generate(failure);

    System.out.println(fingerprint.getId());
    System.out.println(fingerprint.getRootCause());
    System.out.println(fingerprint.getSignature());
}

Example output:

BUGDNA-7A3F21C98B64E120
java.lang.NullPointerException
UserService#getUser

A fingerprint contains more than an ID. It also exposes:

• The deepest root-cause exception
• The simple and fully qualified origin
• The normalised frames used for grouping
• The outer-to-inner cause chain
• A simplified failure chain
• A stability confidence score
• An impact-based priority
• A broad failure category
• An operational root-cause family

For a compact, log-friendly explanation:

System.out.println(fingerprint.explain());

BUGDNA-7A3F21C98B64E120

Root Cause:
NullPointerException

Origin:
UserService#getUser

Confidence:
98%

Failure Chain:
UserController -> UserService

From individual exceptions to operational signals

A stable ID is useful on its own, but it becomes much more valuable when failures are aggregated.

BugDNA includes a thread-safe, in-memory `FailureTracker`:

FailureTracker tracker = new FailureTracker();

tracker.capture(firstFailure);
tracker.capture(firstFailure);
tracker.capture(secondFailure);

System.out.println(tracker.topFailureReport());

Example:

Top 10 Failure Signatures
BUGDNA-001
Count: 2
BUGDNA-002
Count: 1

The tracker can provide structured aggregates for dashboards or application code, not just text reports. It also records a bounded timeline of recent occurrences. That timeline enables burst detection, which can answer questions such as:

Did this failure occur occasionally throughout the day, or did it suddenly reach 300 occurrences per minute?

Different fingerprints can also be grouped into an operational family. A connection refusal, socket timeout, and exhausted connection pool may have different exact stack signatures but still point to the same larger incident:

DATABASE_CONNECTIVITY

Importantly, the message text may be used as heuristic evidence for the family classification, but it is never included in the fingerprint hash. Exact identity and broader operational classification remain separate concerns.

Adding impact context

A stack trace alone cannot tell you how urgent a failure is.

One exception affecting a background cleanup task is not necessarily equivalent to the same exception affecting 500 customers. For that reason, BugDNA only assigns a priority when the application supplies impact context:

FailureContext context = FailureContext.of(
        125,   // occurrences
        18,    // affected users
        false  // fatal
);

Fingerprint fingerprint = BugDna.generate(failure, context);
System.out.println(fingerprint.getPriority());

This example produces `HIGH`.

Without impact data, the priority is `UNKNOWN`. That is more honest than inferring business severity from an exception class.

Automatic Spring Boot capture

For Spring Boot applications, BugDNA provides a starter targeting Java 17 and Spring Boot 4.x:

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

The starter can be enabled explicitly:

@EnableBugDna
@SpringBootApplication
class Application {
}

Unhandled Spring MVC and WebFlux exceptions are then fingerprinted, logged, and recorded automatically:

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

BugDNA does not replace Spring’s normal error handling. The MVC integration returns control to Spring’s exception resolution flow, and the WebFlux integration re-emits the same error. It acts as a diagnostic infrastructure rather than an HTTP error response framework.

The starter also integrates with:

• SLF4J MDC
• Spring Boot Actuator
• Micrometer
• Prometheus-compatible metrics

MDC fields can include the fingerprint ID, confidence, category, family, and priority. Micrometer exposes total and unique failure gauges, while the optional Actuator endpoint returns recent fingerprint snapshots.

Background jobs, message listeners, and manually created threads can use the Spring-managed service directly:

Fingerprint fingerprint = bugDna.fingerprint(failure);

Comparing deployments

One of the most practical uses of stable failure identities is regression analysis.

Given fingerprints observed in versions `1.2.0` and `1.3.0`, BugDNA can classify them as:

• New: present only in the newer deployment
• Resolved: present only in the older deployment
• Recurring: present in both deployments

DeploymentComparison comparison = RegressionDetector.compare(
        new DeploymentSnapshot("1.2.0", previousFingerprints),
        new DeploymentSnapshot("1.3.0", currentFingerprints)
);

System.out.println(comparison.report());

Version 1.2.0 -> Version 1.3.0

New fingerprints: 4
Resolved fingerprints: 12
Recurring fingerprints: 8

Occurrence counts do not change these classifications. This comparison answers whether a signature exists in each deployment, while the tracker and metrics answer how often it occurred.

When a refactor changes an exact fingerprint, BugDNA can compare two fingerprints for similarity and to explain structural differences such as a changed method, origin class, root cause, or normalised call path.

Analysing existing logs from the command line

BugDNA also includes a small CLI for logs that already contain `BUGDNA-*` IDs:

bugdna analyze app.log

Unique Failures: 2

BUGDNA-001 : 42
BUGDNA-002 : 7

Two log files can be compared directly:

bugdna compare 1.2.0 app-v1.log 1.3.0 app-v2.log

The CLI intentionally does not attempt to reconstruct fingerprints from arbitrary stack-trace text. It counts IDs that were generated at runtime, preserving the same identity model from application to analysis.

Design boundaries

BugDNA is intentionally small, but its boundaries matter.

The core tracker and Spring repository are in-memory. Counts and recent snapshots reset when the process restarts. The recent timeline is bounded, while the aggregate state retains one entry per unique fingerprint until it is cleared or the process ends.

That makes BugDNA useful as a lightweight application component, but it is not a replacement for a persistent observability infrastructure. Applications that need long-term history should export fingerprint IDs and aggregates to their existing logging, metrics, tracing, or storage platform.

Failure categories and families are heuristic operational metadata. They can help group-related symptoms, but they should not replace domain-specific exception handling or incident diagnosis.

Finally, fingerprints retain class and method names. Actuator endpoints and logs should be protected according to the same security and privacy standards as other application diagnostics.

Why stable failure identity matters

A handle lets a team say:

• “This deployment introduced four new failure signatures.”
• “This exact bug occurred 1,003 times.”
• “Three different signatures belong to the same database connectivity incident.”
• “The failure moved from one method to another after the refactor.”
• “The current spike is a burst, not normal background noise.”

BugDNA does not remove the need for stack traces. It gives those stack traces a consistent identity so they can participate in the rest of an engineering system.

The project is available on GitHub, with the core and Spring Boot
artifacts published through Maven Central.

Giving Java Exceptions a Stable Identity with BugDNA was originally published in Stackademic on Medium, where people are continuing the conversation by highlighting and responding to this story.