Skip to content

README.md

Latest commit

 

History

History
197 lines (151 loc) · 5.33 KB

README.md

File metadata and controls

197 lines (151 loc) · 5.33 KB
Raw

Publish to Maven Central CodeQL Quality Gate Status

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

Project

GitAds Sponsored

Sponsored by GitAds