org.axonframework.tracing

Interface SpanFactory

All Known Implementing Classes:

LoggingSpanFactory, 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 Summary

Modifier and Type	Method and Description
default Span	createChildHandlerSpan(Supplier<String> operationNameSupplier, Message<?> parentMessage, Message<?>... linkedParents) Creates a new Span which is part of the current trace.
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.
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.
Span	createInternalSpan(Supplier<String> operationNameSupplier) Creates a new Span linked to the currently active span.
Span	createInternalSpan(Supplier<String> operationNameSupplier, Message<?> message) Creates a new Span linked to the currently active span.
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.
Span	createRootTrace(Supplier<String> operationNameSupplier) Creates a new Span without any parent trace.
<M extends Message<?>> M	propagateContext(M message) Propagates the currently active trace and span to the message.
void	registerSpanAttributeProvider(SpanAttributesProvider provider) Registers an additional SpanAttributesProvider to the factory.

Method Detail

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.