Package com.tnsai.quality.sampling

Class SamplingAgentEventPublisher

java.lang.Object
com.tnsai.quality.sampling.SamplingAgentEventPublisher
All Implemented Interfaces:
com.tnsai.observability.events.AgentEventPublisher
public final class SamplingAgentEventPublisher extends Object implements com.tnsai.observability.events.AgentEventPublisher
AgentEventPublisher decorator that consults an EventSamplingPolicy before delegating each publish call (issue #82).

Why a decorator: keeps the AgentEventPublisher SPI in tnsai-core unchanged. Sampling is opt-in by wrapping: 


 AgentEventPublisher slf4j   = new Slf4jAgentEventPublisher();
 AgentEventPublisher sampled = new SamplingAgentEventPublisher(
         slf4j, SamplingPolicies.production());

Decision flow: each publish call builds a SamplingInput from the event's TnsAIEvent.eventType(), the supplied EventLevel, and the active EventContext; the policy returns a SamplingDecision and the decorator publishes only when SamplingDecision.shouldPublish() is true.

Two publish overloads: when the level-aware overload is called, the decorator uses the supplied level + context directly. When the bare publish(event) overload is called, the decorator falls back to EventLevel.INFO + the configured Supplier for context. INFO is the rfc5424-aligned operational default — most events worth publishing are at INFO unless the caller said otherwise.

Composition: stacks naturally with other decorators — wrap inside RedactingAgentEventPublisher so sampled events are redacted on the way out, or wrap outside so the redactor only runs on captured events (cheaper for high-drop policies).

isEnabled fast-path: pass-through to the delegate. Sampling happens at publish time — there is no policy decision available without an event in hand, so we don't second-guess the publisher's level filter here.

Thread-safety: stateless beyond the immutable delegate + policy + context supplier. Policies must themselves be thread-safe (the SPI requires it).

Since:
0.9.0 (issue #82)

  • Constructor Summary

    Constructors
    Constructor
    Description
    SamplingAgentEventPublisher(com.tnsai.observability.events.AgentEventPublisher delegate, EventSamplingPolicy policy)
    Wrap delegate with sampling using policy, falling back to EventContext.empty() for the bare publish(event) overload.
    SamplingAgentEventPublisher(com.tnsai.observability.events.AgentEventPublisher delegate, EventSamplingPolicy policy, Supplier<com.tnsai.observability.events.EventContext> contextSupplier)
    Wrap delegate with sampling using policy and a contextSupplier that returns the EventContext to attach to bare publish(event) calls.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    isEnabled(com.tnsai.observability.events.EventLevel level)
     
    void
    publish(com.tnsai.events.TnsAIEvent event)
     
    void
    publish(com.tnsai.events.TnsAIEvent event, com.tnsai.observability.events.EventLevel level, com.tnsai.observability.events.EventContext context)
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • SamplingAgentEventPublisher

      public SamplingAgentEventPublisher(com.tnsai.observability.events.AgentEventPublisher delegate, EventSamplingPolicy policy)
      Wrap delegate with sampling using policy, falling back to EventContext.empty() for the bare publish(event) overload.

    • SamplingAgentEventPublisher

      public SamplingAgentEventPublisher(com.tnsai.observability.events.AgentEventPublisher delegate, EventSamplingPolicy policy, Supplier<com.tnsai.observability.events.EventContext> contextSupplier)
      Wrap delegate with sampling using policy and a contextSupplier that returns the EventContext to attach to bare publish(event) calls.
      Throws:
      NullPointerException - if any arg is null

  • Method Details

    • publish

      public void publish(com.tnsai.events.TnsAIEvent event)
      Specified by:
      publish in interface com.tnsai.observability.events.AgentEventPublisher

    • publish

      public void publish(com.tnsai.events.TnsAIEvent event, com.tnsai.observability.events.EventLevel level, com.tnsai.observability.events.EventContext context)
      Specified by:
      publish in interface com.tnsai.observability.events.AgentEventPublisher

    • isEnabled

      public boolean isEnabled(com.tnsai.observability.events.EventLevel level)
      Specified by:
      isEnabled in interface com.tnsai.observability.events.AgentEventPublisher