Package com.tnsai.observability.events

Interface AgentEventPublisher

All Known Implementing Classes:

CapturingAgentEventPublisher, CompositeAgentEventPublisher, Slf4jAgentEventPublisher

public interface AgentEventPublisher

Service-side fan-out point for observability events.

Distinct from TnsAIEventPublisher, which is session-scoped reactive streaming for live UI consumers (AG-UI, web socket clients). AgentEventPublisher is the logging side: fire-and-forget, no per-session lifecycle, sinks are SLF4J / OTel logs / in-memory ring buffer / external trackers (Sentry, LangFuse, etc.).

Discovered via ServiceLoader; the framework auto-composes all discovered publishers via CompositeAgentEventPublisher so adding a new sink is just dropping a JAR with a META-INF/services/ entry.

Implementations shipped

• Slf4jAgentEventPublisher — default, JSON-serializes the event and emits via SLF4J at the mapped level. Logstash encoder picks it up for structured sinks.
• CompositeAgentEventPublisher — fan-out wrapper used to combine multiple publishers (used internally; consumers can wrap too).
• CapturingAgentEventPublisher — test utility that holds events in memory for assertion. Not registered via SPI.

Since:

0.5.0 (issue #78)

Method Summary

Modifier and Type	Method	Description
default boolean	isEnabled(EventLevel level)	Should this publisher emit at the given level?
void	publish(TnsAIEvent event)	Publish a single event.
default void	publish(TnsAIEvent event, EventLevel level, EventContext context)	Publish a single event with explicit level / context overrides.

Method Details

publish

void publish(TnsAIEvent event)

Publish a single event. Implementations must be safe to call from any thread; they may queue, batch, or write directly. Errors during publication must not propagate to the caller — log and drop.

publish

default void publish(TnsAIEvent event,
 EventLevel level,
 EventContext context)

Publish a single event with explicit level / context overrides. Useful when emitting an event at a level different from the event's default (e.g. demoting a verbose ChatEvent to DEBUG in production).

Default implementation ignores overrides — concrete publishers that care about level filtering (Slf4j) override this.

isEnabled

default boolean isEnabled(EventLevel level)

Should this publisher emit at the given level? Used to short-circuit expensive event construction when the publisher will discard the event anyway.

Default: always true (no level filtering).