Package org.axonframework.messaging.tracing

Interface SpanFactory

All Known Implementing Classes:
MultiSpanFactory, NoOpSpanFactory, OpenTelemetrySpanFactory
public interface SpanFactory
The SpanFactory is responsible for making spans in a way the chosen tracing provider is compatible with.

Each span has an operation name and span kind. From the operation name it should be clear what is happening in the application. For example, use "ClassName.method MessageName" to indicate a message payload being handled.

Spans can have tags, which are provided by SpanAttributesProviders. By default, any time a message is used while creating a span should invoke all configured SpanAttributesProviders and set those tags on the created span.

The factory should support these types of spans:

  • New root trace spans: These create an entirely new trace without parent. Use this for asynchronous calls that we want to measure the performance individually of. For example, snapshotting (which has no influence on a business process).
  • New handler spans: This creates a new span in an already existing trace. The span that was active when the message was dispatched will be linked to it. It will be of the handling type
  • New dispatch spans: This creates a new span in an already existing trace. It will be of a dispatching type.
  • New internal span: This creates a new sub-span in an already active span. Use this for measuring individual parts of an already existing span. For example, measuring how long it takes to load the aggregate when handling an event.

Check the individual method's javadoc more information on each type.

Since:
4.6.0
Author:
Mitchell Herrijgers

  • Method Details

    • createRootTrace

      Span createRootTrace(Supplier<String> operationNameSupplier)
      Creates a new Span without any parent trace. This should be used for logical start point of asynchronous calls that are not related to a message. For example snapshotting an aggregate.

      In monitoring systems, this Span will be the root of the trace.

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      Returns:
      The created Span.

    • createLinkedHandlerSpan

      default Span createLinkedHandlerSpan(Supplier<String> operationNameSupplier, Message parentMessage, Message... linkedParents)
      Creates a new Span which becomes its own separate trace, linked to the previous span. Useful for asynchronous invocations, such as handling an event in a StreamingEventProcessor.

      In monitoring systems, this Span will start a separate trace linked to the previous one.

      The message's name will be concatenated with the operationName, see SpanUtils.determineMessageName(Message).

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      parentMessage - The message that is being handled.
      linkedParents - Optional parameter, providing this will link the provided message(s) to the current, in addition to the original.
      Returns:
      The created Span.

    • createChildHandlerSpan

      default Span createChildHandlerSpan(Supplier<String> operationNameSupplier, Message parentMessage, Message... linkedParents)
      Creates a new Span which is part of the current trace. The message attributes will be added to the span, based on the provided SpanAttributesProviders for additional debug information.

      In monitoring systems, this Span will be part of another trace.

      The message's name will be concatenated with the operationName, see SpanUtils.determineMessageName(Message).

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      parentMessage - The message that is being handled.
      linkedParents - Optional parameter, providing this will link the provided message(s) to the current, in addition to the original.
      Returns:
      The created Span.

    • createHandlerSpan

      Span createHandlerSpan(Supplier<String> operationNameSupplier, Message parentMessage, boolean isChildTrace, Message... linkedParents)
      Creates a new Span linked to asynchronously handling a Message, for example when handling a command from Axon Server. The message attributes will be added to the span, based on the provided SpanAttributesProviders for additional debug information.

      In monitoring systems, this Span will be the root of the trace.

      The message's name will be concatenated with the operationName, see SpanUtils.determineMessageName(Message).

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      parentMessage - The message that is being handled.
      isChildTrace - Whether to force the span to be a part of the current trace. This means not linking, but setting a parent.
      linkedParents - Optional parameter, providing this will link the provided message(s) to the current, in addition to the original.
      Returns:
      The created Span.

    • createDispatchSpan

      Span createDispatchSpan(Supplier<String> operationNameSupplier, Message parentMessage, Message... linkedSiblings)
      Creates a new Span linked to dispatching a Message, for example when sending a command to Axon Server. The message attributes will be added to the span, based on the provided SpanAttributesProviders for additional debug information.

      In monitoring systems, this Span will be part of another trace.

      Before asynchronously dispatching a message, add the tracing context to the message, using propagateContext(Message) to the message's metadata.

      The message's name will be concatenated with the operationName, see SpanUtils.determineMessageName(Message).

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      parentMessage - The message that is being handled.
      linkedSiblings - Optional parameter, providing this will link the provided messages to the current.
      Returns:
      The created Span.

    • createInternalSpan

      Span createInternalSpan(Supplier<String> operationNameSupplier)
      Creates a new Span linked to the currently active span. This is useful for tracing different parts of framework logic, so we can time what has the most impact.

      In monitoring systems, this Span will be part of another trace.

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      Returns:
      The created Span.

    • createInternalSpan

      Span createInternalSpan(Supplier<String> operationNameSupplier, Message message)
      Creates a new Span linked to the currently active span. This is useful for tracing different parts of framework logic, so we can time what has the most impact.

      The message supplied is used to provide a clearer name, based on SpanUtils.determineMessageName(Message), and to add the message's attributes to the span.

      In monitoring systems, this Span will be part of another trace.

      Parameters:
      operationNameSupplier - Supplier of the operation's name.
      Returns:
      The created Span.

    • registerSpanAttributeProvider

      void registerSpanAttributeProvider(SpanAttributesProvider provider)
      Registers an additional SpanAttributesProvider to the factory.
      Parameters:
      provider - The provider to add.

    • propagateContext

      <M extends Message> M propagateContext(M message)
      Propagates the currently active trace and span to the message. It should do so in a way that the context can be retrieved by the createLinkedHandlerSpan(Supplier, Message, Message[]) method. The most efficient method currently known is to enhance the message's metadata.

      Since messages are immutable, the method returns the enhanced message. This enhanced message should be used during dispatch instead of the original message.

      Type Parameters:
      M - The message's type.
      Parameters:
      message - The message to enhance.
      Returns:
      The enhanced message.