Package org.axonframework.messaging.eventhandling.tracing

Class TracingEventHandlingComponent

java.lang.Object
org.axonframework.messaging.eventhandling.DelegatingEventHandlingComponent
org.axonframework.messaging.eventhandling.tracing.TracingEventHandlingComponent
All Implemented Interfaces:
DescribableComponent, MessageHandler, EventHandler, EventHandlingComponent, ReplayStatusChangedHandler, ResetHandler
@Internal public final class TracingEventHandlingComponent extends DelegatingEventHandlingComponent
Delegating EventHandlingComponent decorator that opens a per-event handler span around each event handled, and -- for streaming-processor batches -- a single enclosing batch span.

On each handle(EventMessage, ProcessingContext) a handler span (kind consumer) is opened branch-scoped via Span.branchStream(ProcessingContext, java.util.function.Function): its SpanScope is carried on a context branch passed to the delegate, the handling window executes within that scope, and the scope closes when this event's own result stream terminates -- not at batch end. Carrying the scope on a branch, rather than writing it to the shared batch context, is what lets downstream children (dispatch spans, asynchronous continuations, and provider-instrumented work) parent under their own event even when a later event in the same batch has since started on the shared context.

The streaming flag selects the trace topology; it does not make assumptions about how or where event handling runs. When streaming is false, each handler span continues the publisher's trace and no batch span is created. When streaming is true, a handler span continues the publisher's trace only in distributed-in-same-trace mode for sufficiently fresh events. Otherwise, it is a child of the enclosing batch span and links back to the publisher, or starts a new trace with the same publisher link when batch tracing is disabled.

The batch span, by contrast, is context-lifetime: it is opened lazily on the first event of a batch, only for streaming processors, and only outside distributed-in-same-trace mode (in that mode per-event spans continue their publishers' traces, so a batch root would dangle without meaningful children). It is bound to the shared batch context's root via Span.coverLifecycle(ProcessingContext), so it legitimately stays the active span there for every lifecycle action (commit, etc.) that runs against that root. A non-streaming processor gets no separate batch span.

Every span this component creates -- the batch span and the per-event handler span -- carries the owning event processor's name under the PROCESSOR_NAME_ATTRIBUTE attribute (when the name is known), so spans of different processors handling the same event type stay distinguishable in APM UIs.

This decorator is registered by MessagingTracingConfigurationEnhancer; it is never instantiated directly by applications.

Since:
5.3.0
Author:
Mateusz Nowak

  • Constructor Details

    • TracingEventHandlingComponent

      public TracingEventHandlingComponent(EventHandlingComponent delegate, SpanFactory spanFactory)
      Initializes a tracing EventHandlingComponent with the non-streaming trace topology (streaming=false), the default sub-toggles (batchTraceEnabled=true, distributedInSameTrace=false, distributedInSameTraceTimeLimit=PT2M), and no processor name.
      Parameters:
      delegate - the event-handling component to delegate to
      spanFactory - the factory producing the tracing spans

    • TracingEventHandlingComponent

      public TracingEventHandlingComponent(EventHandlingComponent delegate, SpanFactory spanFactory, @Nullable String processorName, boolean streaming, boolean batchTraceEnabled, boolean distributedInSameTrace, Duration distributedInSameTraceTimeLimit)
      Initializes a tracing EventHandlingComponent wrapping the given delegate, obtaining spans from the given spanFactory.
      Parameters:
      delegate - the event-handling component to delegate to
      spanFactory - the factory producing the tracing spans
      processorName - the name of the event processor owning the delegate, attached to every created span under the processor-name attribute; or null when unknown, in which case no attribute is attached
      streaming - whether to use the streaming trace topology; when false, handler spans continue the publisher's trace and no batch span is opened; when true, the other tracing settings determine the handler spans' parent and whether a batch span is opened
      batchTraceEnabled - whether an enclosing batch span is opened for streaming batches
      distributedInSameTrace - when true, a streaming handler span continues the publisher's trace and no batch span is opened; when false, the handler is parented to an enabled batch span and linked to its publisher, or starts a linked trace when batch tracing is disabled
      distributedInSameTraceTimeLimit - how recent an event must be to continue the publisher's trace when distributedInSameTrace is true; older events (e.g. replays) start their own trace linked back to the publisher instead of stretching the publisher's long-finished trace

  • Method Details

    • handle

      public MessageStream.Empty<Message> handle(EventMessage event, ProcessingContext context)
      Description copied from interface: EventHandler
      Handles the given event within the given context.

      The result of handling is an empty stream.

      Specified by:
      handle in interface EventHandler
      Overrides:
      handle in class DelegatingEventHandlingComponent
      Parameters:
      event - The event to handle.
      context - The context to the given event is handled in.
      Returns:
      An empty stream containing nothing.

    • describeTo

      public void describeTo(ComponentDescriptor descriptor)
      Description copied from interface: DescribableComponent
      Describe the properties of this DescribableComponent with the given descriptor.

      Components should call the appropriate describeProperty methods on the descriptor to register their properties. The descriptor is responsible for determining how these properties are formatted and structured in the final output.

      Best Practices: As a general rule, all relevant fields of a DescribableComponent implementation should be described in this method. However, developers have discretion to include only the fields that make sense in the context. Not every field may be meaningful for description purposes, especially internal implementation details. Furthermore, components might want to expose different information based on their current state. The final decision on what properties to include lies with the person implementing the describeTo method, who should focus on providing information that is useful for understanding the component's configuration and state.

      Example implementation: 

       public void describeTo(ComponentDescriptor descriptor) {
     descriptor.describeProperty("name", this.name);
     descriptor.describeProperty("enabled", this.enabled);
     descriptor.describeProperty("configuration", this.configuration); // A nested component
     descriptor.describeProperty("handlers", this.eventHandlers);      // A collection
 }
      Specified by:
      describeTo in interface DescribableComponent
      Overrides:
      describeTo in class DelegatingEventHandlingComponent
      Parameters:
      descriptor - The component descriptor to describe this DescribableComponentn its properties in.