Package com.tnsai.observability.errors

Class ErrorEmitter

java.lang.Object
com.tnsai.observability.errors.ErrorEmitter
public final class ErrorEmitter extends Object
Single emission point for ErrorReport construction.

Use this from any framework or consumer code that catches an exception and wants it surfaced as a structured, dedup-able observability record: 


 try {
     llmClient.chat(request);
 } catch (LLMException e) {
     ErrorReport report = ErrorEmitter.from(e)
             .category(ErrorCategory.TRANSIENT)
             .attributes(Map.of("provider", "openai", "model", "gpt-4o"))
             .recoveryAction("RETRIED")
             .recoveryAttempts(2)
             .build();
     // report → ErrorReportSink (your aggregator) or ErrorReports.publish(report);
     throw e;
 }

from(throwable) pre-populates errorClass, errorCode (if a TnsAIException), message, retryable, the cause chain, the stack trace digest, and the fingerprint. The current AgentContext is captured automatically. Caller adds the remaining classification (category, attributes, recovery action).

Pure factory — no I/O, no global state, no side effects. Wiring to a sink (Prometheus, log aggregator) is left to a separate ErrorReports publisher (out of scope for this PR; see AgentEventPublisher pattern in com.tnsai.observability.events).

Since:
0.5.0 (issue #86)

  • Method Details

    • from

      public static ErrorReport.Builder from(Throwable t)
      Begin building an ErrorReport from a throwable. Pre-populates everything that can be derived from the throwable itself; caller fills in category (required for meaningful classification), attributes, and any recovery info.

    • report

      public static ErrorReport report(Throwable t, ErrorCategory category, Map<String,Object> attributes, Map<String,String> relevantAttributes)
      Convenience: full report with the caller's classification + attributes applied. The fingerprint is recomputed to incorporate relevantAttributes (so tools / providers / models that should partition the bug get distinct fingerprints).
      Parameters:
      t - throwable; required
      category - required classification
      attributes - arbitrary diagnostic fields (low-cardinality recommended)
      relevantAttributes - subset of attributes that participates in the fingerprint (e.g. "provider", "model" for LLM errors). Pass empty for no per-attribute partitioning.