bugdna

BugDNA converts Java exceptions into deterministic fingerprints for grouping, tracking, logging, and comparing recurring failures.

BUGDNA-7A3F21

Features

• Deterministic exception fingerprints
• PII-safe normalization for emails and numeric identifiers
• Fingerprint knowledge base lookup for owners and runbooks
• Fluent JUnit-friendly fingerprint assertions
• Root-cause, category, stability, and priority analysis
• Root-cause family clustering across different fingerprints
• Failure dependency graphs from causal chains
• Timestamped failure timelines and burst detection
• Deployment regression detection for new, resolved, and recurring fingerprints
• Fingerprint drift detection for recurring IDs whose signature shape changes
• In-memory concurrent failure aggregation
• Top failure reports for batch jobs
• Most-common skip reason analysis
• Topic-aware consumer failure tracking
• Log-file analysis CLI
• Log-to-log signature comparison
• Fingerprint similarity and regression diffs
• Build-time exception-handling validation for Maven and Gradle
• Spring MVC and WebFlux unhandled-exception capture
• SLF4J MDC integration
• OpenTelemetry span enrichment
• Actuator and Micrometer metrics

Requirements

Module	Java	Framework
Core library	8+	None
Build scanner	8+	Maven or Gradle
Spring Boot starter	17+	Spring Boot 4.x
CLI	8+	None

Installation

Core library:

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

Spring Boot starter:

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

CLI:

mvn -pl bugdna-cli clean package
bin/bugdna analyze app.log

Maven build-time scan:

mvn bugdna:scan

Gradle build-time scan:

plugins {
    id 'io.github.arnabnandy7.bugdna' version '1.1.2'
}

./gradlew bugdnaScan

The build scanner detects empty catch blocks, generic Exception/Throwable usage, and likely unhandled checked-exception APIs. It reports source locations and fails the build by default. Use -Dbugdna.failOnIssues=false for Maven or bugdna { failOnIssues = false } for Gradle to warn only.

Gradle coordinates are available in the getting-started guide.

Quick Start

Fingerprint fingerprint = BugDna.generate(exception);

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

Assert fingerprints in automated tests:

import static io.github.bugdna.BugDnaAssertions.assertThat;

assertThat(fingerprint)
        .hasCategory(FailureCategory.DATABASE)
        .hasRootCause(SQLTimeoutException.class);

Render causal dependencies:

System.out.println(BugDna.dependencyGraph(exception).report());

BUGDNA-001
 └─ BUGDNA-014
      └─ BUGDNA-022

Attach runbooks and ownership to stable IDs:

BUGDNA-001:
  title: Database Pool Exhaustion
  owner: Platform Team
  runbook: runbooks/db-pool.md

FingerprintKnowledge context = BugDna.lookup("BUGDNA-001");
System.out.println(context.getRunbook());

Track recurring failures:

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

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

Spring Boot:

@EnableBugDna
@SpringBootApplication
class Application {
}

Unhandled Spring MVC and WebFlux exceptions are fingerprinted, logged, aggregated, and exposed to optional Actuator and Micrometer integrations.

Documentation

• Documentation index
• Getting started
• Core vs Spring Boot starter
• Core library
• Failure tracking
• Spring Boot starter
• Command-line interface
• Configuration reference
• Observability
• API reference
• Architecture and data handling
• Troubleshooting
• Migration guide
• FAQ

Project

• Changelog
• Contributing
• License
• Core artifact
• Starter artifact

GitAds Sponsored