getting-started.md

Getting Started

Choose an Artifact

Use the core artifact for plain Java applications:

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

Gradle:

implementation "io.github.arnabnandy7:bugdna:1.1.2"

Use the starter for Spring Boot applications:

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

Gradle:

implementation "io.github.arnabnandy7:bugdna-spring-boot-starter:1.1.2"

The starter already depends on the core artifact.

Generate a Fingerprint

import io.github.bugdna.BugDna;
import io.github.bugdna.Fingerprint;

try {
    runApplicationCode();
} catch (Exception exception) {
    Fingerprint fingerprint = BugDna.generate(exception);
    System.out.println(fingerprint.getId());
}

Example:

BUGDNA-7A3F21

The actual identifier uses 16 uppercase hexadecimal characters after the prefix.

Inspect the Failure

System.out.println(fingerprint.getRootCause());
System.out.println(fingerprint.getSignature());
System.out.println(fingerprint.getQualifiedSignature());
System.out.println(fingerprint.getCategory());
System.out.println(fingerprint.getStabilityScore());

Example output:

java.lang.NullPointerException
UserService#getUser
com.example.UserService#getUser
UNKNOWN
90

For a log-friendly block:

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

BUGDNA-7A3F21

Root Cause:
NullPointerException

Origin:
UserService#getUser

Confidence:
90%

Failure Chain:
UserController -> UserService

Track Recurring Failures

FailureTracker tracker = new FailureTracker();
tracker.capture(exception);

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

The tracker is thread-safe and in-memory only.

After repeated captures, tracker.report() groups occurrences by fingerprint:

2 unique failure signatures

BUGDNA-001
Count: 12

BUGDNA-002
Count: 3

Enable Spring Capture

The starter participates in Spring Boot auto-configuration. You may also make the integration explicit:

import io.github.bugdna.spring.EnableBugDna;

@EnableBugDna
@SpringBootApplication
class Application {
}

Unhandled Spring MVC and WebFlux exceptions then pass through BugDNA without replacing Spring's normal exception handling.

Next Steps

• Learn fingerprint behavior in Core library.
• Configure aggregation in Failure tracking.
• Configure Spring in Spring Boot starter.
• Add metrics and MDC in Observability.