Package com.tnsai.observability.errors

Class ErrorReports

java.lang.Object

com.tnsai.observability.errors.ErrorReports

public final class ErrorReports
extends Object

Static facade for publishing ErrorReports.

The framework's "one-line emit" entry point — consumers in catch blocks call:

 try {
     llmClient.chat(request);
 } catch (LLMException e) {
     ErrorReports.publish(e, ErrorCategory.TRANSIENT,
             Map.of("provider", "openai", "model", "gpt-4o"));
     throw e;  // rethrow — emission is observation, not handling
 }
 

The active publisher is one of:

• SPI-discovered (default): every ErrorReportPublisher found through Java service-provider discovery is wrapped in a CompositeErrorReportPublisher on first use. The framework ships Slf4jErrorReportPublisher as the only SPI-registered publisher; consumers add Sentry / Loki / custom publishers by dropping a JAR with a META-INF/services/com.tnsai.observability.errors.ErrorReportPublisher file.
• Explicit override: setPublisher(ErrorReportPublisher) replaces the discovered chain entirely. Use in tests (CapturingErrorReportPublisher) or in deployments that want a single-purpose pipeline.

Thread-safety: the active publisher reference is volatile + atomically swapped via AtomicReference. Multiple threads publishing concurrently see a consistent publisher. SPI discovery is one-shot (lazy, double-checked) — switching publishers via setPublisher(ErrorReportPublisher) discards the discovered chain and uses the new one verbatim.

Reset between tests: call resetForTesting() in @AfterEach to drop any test-installed publisher and rediscover via SPI on the next publish(ErrorReport) call. Tests that forget this leak the test publisher across methods.

Since:

0.5.0 (issue #86)

Method Summary

Modifier and Type	Method	Description
static ErrorReportPublisher	activePublisher()	Read the currently-active publisher, or null if no publisher has been bound (and SPI discovery hasn't run yet).
static void	publish(ErrorReport report)	Publish an already-constructed ErrorReport.
static void	publish(Throwable t, ErrorCategory category, Map<String,Object> attributes)	Convenience: capture-and-publish in one call.
static void	resetForTesting()	Drop any test-installed publisher and force the next publish(ErrorReport) to re-run SPI discovery.
static void	setPublisher(ErrorReportPublisher publisher)	Replace the active publisher entirely.

Methods inherited from class java.lang.Object

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

Method Details

publish

public static void publish(ErrorReport report)

Publish an already-constructed ErrorReport. Errors during publication are swallowed — the caller is in an error path; making it harder is the wrong move.

publish

public static void publish(Throwable t,
 ErrorCategory category,
 Map<String,Object> attributes)

Convenience: capture-and-publish in one call. Equivalent to publish(ErrorEmitter.report(t, category, attributes, Map.of())).

Parameters:

t - throwable; required

category - required classification

attributes - diagnostic fields (low-cardinality recommended)

setPublisher

public static void setPublisher(ErrorReportPublisher publisher)

Replace the active publisher entirely. Subsequent publish(ErrorReport) calls hit only the supplied publisher; SPI discovery is bypassed until resetForTesting() or another setPublisher.

Pass null to discard the override and re-enter SPI-discovery mode (next publish triggers a fresh ServiceLoader walk).

activePublisher

public static ErrorReportPublisher activePublisher()

Read the currently-active publisher, or null if no publisher has been bound (and SPI discovery hasn't run yet). Useful for tests that want to assert teardown happened.

resetForTesting

public static void resetForTesting()

Drop any test-installed publisher and force the next publish(ErrorReport) to re-run SPI discovery. Call from @AfterEach in tests that override the publisher.