Package com.tnsai.observability.errors

Class ErrorFingerprint

java.lang.Object

com.tnsai.observability.errors.ErrorFingerprint

public final class ErrorFingerprint
extends Object

Deterministic fingerprint for an error instance class.

Two errors with the same fingerprint are treated as the same bug for purposes of dedup, alerting, and dashboards. This is the analogue of Sentry/Rollbar/Datadog "issue grouping" — without a stable fingerprint the same bug from 1000 concurrent users becomes 1000 separate alerts.

Fingerprint inputs

• errorClass — fully-qualified throwable type
• errorCode — TNSAI-XXX (when present); two errors with the same stack but different codes are distinct bugs
• stackTraceDigest — from StackTraceNormalizer.digest(Throwable)
• relevantAttributes — caller-selected, low-cardinality fields (e.g. provider/model for LLM errors, tool name for tool errors). Per-request data MUST NOT be passed here or every request gets its own fingerprint and dedup collapses.

Output: a 16-hex-char SHA-256 prefix (64 bits). Same input → same output across JVM restarts and across hosts (no thread-local state, no timestamps, no PID, no random seed).

Since:

0.5.0 (issue #86)

Method Summary

Modifier and Type	Method	Description
static String	of(String errorClass, String errorCode, String stackTraceDigest, Map<String,String> relevantAttributes)	Compute the fingerprint from already-prepared inputs.
static String	of(Throwable t, String errorCode, Map<String,String> relevantAttributes)	Convenience: derive stackTraceDigest from the throwable's normalized stack via StackTraceNormalizer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

of

public static String of(String errorClass,
 String errorCode,
 String stackTraceDigest,
 Map<String,String> relevantAttributes)

Compute the fingerprint from already-prepared inputs.

Parameters:

errorClass - fully-qualified throwable class name; required

errorCode - framework error code (TNSAI-XXX) or null/blank if none

stackTraceDigest - from StackTraceNormalizer.digest(Throwable); required

relevantAttributes - low-cardinality contextual attributes; null treated as empty

Returns:

16-character lowercase hex string

of

public static String of(Throwable t,
 String errorCode,
 Map<String,String> relevantAttributes)

Convenience: derive stackTraceDigest from the throwable's normalized stack via StackTraceNormalizer.