Package com.tnsai.observability.events

package com.tnsai.observability.events

Observability event schema + thread-local correlation context.

Complements the existing com.tnsai.events reactive/streaming layer: TnsAIEventPublisher is session-scoped fan-out for live UI consumers, while AgentEventPublisher is the observability-side fire-and-forget sink layer (SLF4J / OTel logs / in-memory buffer / external trackers).

Key types

• EventLevel — severity.
• EventContext — correlation fields (tenant, session, trace, agent, role, capabilities, group, conversation, extensions).
• AgentContext — thread-local holder, MDC-synced, with try-with-resources enter(ctx) and async wrap(...) helpers.
• AgentEventPublisher — sink SPI (java.util.ServiceLoader).
• Slf4jAgentEventPublisher — default sink: JSON via SLF4J.
• CompositeAgentEventPublisher — fan-out for multiple sinks.
• CapturingAgentEventPublisher — test utility.
• AgentEvents — static facade.

Usage

 try (var ignored = AgentContext.enter(ctx)) {
     AgentEvents.publish(new ChatEvent(...), EventLevel.INFO);
     // every logger.info in this scope also carries MDC fields
     agent.chat(msg);
 }
 

Since:

0.5.0 (issue #78)

Class	Description
AgentContext	Thread-local container for the current EventContext.
AgentContext.Scope	AutoCloseable returned by AgentContext.enter(EventContext) — restores the previous context (or clears entirely if none was active) on close.
AgentEventPublisher	Service-side fan-out point for observability events.
AgentEvents	Static facade for publishing observability events from anywhere in the framework or consumer code.
Breadcrumbs	Per-thread ring buffer of recent operations leading up to a point in time — typically an exception throw.
Breadcrumbs.Breadcrumb	Single recorded operation with timestamp and attributes.
CapturingAgentEventPublisher	In-memory AgentEventPublisher for unit tests — records every published event so the test can assert on them.
CapturingAgentEventPublisher.Captured
CompositeAgentEventPublisher	Fan-out AgentEventPublisher — broadcasts each event to every delegate.
EventContext	Correlation context attached to every observability event.
EventContext.Builder
EventLevel	Severity level for an TnsAIEvent when published as an observability log record.
Slf4jAgentEventPublisher	Default AgentEventPublisher — JSON-serializes the event and writes it via SLF4J at the level corresponding to EventLevel.