Span (Axon Framework 4.9.0 API)

All Known Implementing Classes:

NoOpSpanFactory.NoOpSpan, OpenTelemetrySpan
```
public interface Span
```
Represents a part of the application logic that will be traced. One or multiple spans together form a trace and are often used to debug and monitor (distributed) applications.
The Span is an abstraction for Axon Framework to have tracing capabilities without knowing the specific tracing provider. Calling start() will start the span and make it active to the current thread. For every start invocation, a respective end() should be called as well to prevent scope leaks.
Creating spans is the responsibility of the SpanFactory which should be implemented by the tracing provider of choice.
Important! In order to make this span the parent for any new span created during its execution, makeCurrent() should be called. This method will return a SpanScope, on which SpanScope.close() should be invoked during the same code execution on the same thread. If not, this span will become the unwanted parent of any children. You can make the same span the current for multiple threads at any point in time, as long as you close them before calling end()
Each start() should eventually result in an end() being called, but this does not have to be done on the same thread.

Since:

4.6.0

Author:

Mitchell Herrijgers

See Also:

For more information about creating different kinds of traces.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default Span`	`addAttribute(String key, String value)` Adds an attribute to the span.
`void`	`end()` Ends the span.
`default SpanScope`	`makeCurrent()` Sets the Span as the current for the current thread.
`Span`	`recordException(Throwable t)` Records an exception to the span.
`default void`	`run(Runnable runnable)` Runs a piece of code which will be traced.
`default <T> T`	`runCallable(Callable<T> callable)` Runs a piece of code which will be traced.
`default <T> void`	`runConsumer(Consumer<T> supplier, T consumedObject)` Runs a piece of code that returns a value and which will be traced.
`default <T> T`	`runSupplier(Supplier<T> supplier)` Runs a piece of code that returns a value and which will be traced.
`Span`	`start()` Starts the Span.
`default <T> Callable<T>`	`wrapCallable(Callable<T> callable)` Wraps a `Callable`, propagating the current span context to the actual thread that runs the `Callable`.
`default <T> Consumer<T>`	`wrapConsumer(Consumer<T> supplier)` Wraps a `Consumer`, tracing the invocation.
`default Runnable`	`wrapRunnable(Runnable runnable)` Wraps a `Runnable`, propagating the current span context to the actual thread that runs the `Runnable`.
`default <T> Supplier<T>`	`wrapSupplier(Supplier<T> supplier)` Wraps a `Supplier`, tracing the invocation.

- Method Detail
  - start
```
Span start()
```
    Starts the Span. However, does not set this span as the span of the current thread. See makeCurrent() in order to do so.
    
    Returns:
    
    The span for fluent interfacing.
  - makeCurrent
```
default SpanScope makeCurrent()
```
    Sets the Span as the current for the current thread. The returned SpanScope must be closed before ending the Span, on the same thread, or through a try-with-resources statement in the same thread as this method was called.
    You can make a span current on as many threads as you like, but you have to close every SpanScope, or context will leak into the current thread. Note that if this is neglected, the end() method should warn the user in order to report this back to the framework.
    
    Returns:
    
    The scope of the span that must be closed be
  - end
```
void end()
```
    Ends the span. All scopes should have been closed at this point. In addition, a span can only be ended once.
    If scopes are still open when this method is called, either an exception should be thrown or an error log should be produced to warn the user of the leak. This information can then be reported back to the developers of the framework for a fix.
  - recordException
```
Span recordException(Throwable t)
```
    Records an exception to the span. This will be reported to the APM tooling, which can show more information about the error in the trace. This method does not end the span.
    
    Parameters:
    
    t - The exception to record
    
    Returns:
    
    The span for fluent interfacing.
  - run
```
default void run(Runnable runnable)
```
    Runs a piece of code which will be traced. Exceptions will be caught automatically and added to the span, then rethrown. The span will be started before the execution, and ended after execution. Note that the Runnable will be invoked instantly and synchronously.
    
    Parameters:
    
    runnable - The Runnable to execute.
  - wrapRunnable
```
default Runnable wrapRunnable(Runnable runnable)
```
    Wraps a Runnable, propagating the current span context to the actual thread that runs the Runnable. If you don't wrap a runnable before passing it to an Executor the context will be lost and a new trace will be started.
    
    Parameters:
    
    runnable - The Runnable to wrap
    
    Returns:
    
    A wrapped runnable which propagates the span's context across threads.
  - runCallable
```
default <T> T runCallable(Callable<T> callable)
                   throws Exception
```
    Runs a piece of code which will be traced. Exceptions will be caught automatically and added to the span, then rethrown. The span will be started before the execution, and ended after execution. Note that the Callable will be invoked instantly and synchronously.
    
    Parameters:
    
    callable - The Callable to execute.
    
    Throws:
    
    Exception
  - wrapCallable
```
default <T> Callable<T> wrapCallable(Callable<T> callable)
```
    Wraps a Callable, propagating the current span context to the actual thread that runs the Callable. If you don't wrap a callable before passing it to an Executor the context will be lost and a new trace will be started.
    
    Parameters:
    
    callable - The Callable to wrap
    
    Returns:
    
    A wrapped callable which propagates the span's context across threads.
  - runSupplier
```
default <T> T runSupplier(Supplier<T> supplier)
```
    Runs a piece of code that returns a value and which will be traced. Exceptions will be caught automatically and added to the span, then rethrown. The span will be started before the execution, and ended after execution. Note that the Supplier will be invoked instantly and synchronously.
    
    Parameters:
    
    supplier - The Supplier to execute.
  - wrapSupplier
```
default <T> Supplier<T> wrapSupplier(Supplier<T> supplier)
```
    Wraps a Supplier, tracing the invocation. Exceptions will be caught automatically and added to the span, then rethrown. The span will be started before the execution, and ended after execution.
    
    Parameters:
    
    supplier - The Supplier to wrap
    
    Returns:
    
    A wrapped Supplier
  - runConsumer
```
default <T> void runConsumer(Consumer<T> supplier,
                             T consumedObject)
```
    Runs a piece of code that returns a value and which will be traced. Exceptions will be caught automatically and added to the span, then rethrown. The span will be started before the execution, and ended after execution. Note that the Consumer will be invoked instantly and synchronously.
    
    Parameters:
    
    supplier - The Consumer to execute.
  - wrapConsumer
```
default <T> Consumer<T> wrapConsumer(Consumer<T> supplier)
```
    Wraps a Consumer, tracing the invocation. Exceptions will be caught automatically and added to the span, then rethrown. The span will be started before the execution, and ended after execution.
    
    Parameters:
    
    supplier - The Consumer to wrap
    
    Returns:
    
    A wrapped Consumer
  - addAttribute
```
default Span addAttribute(String key,
                          String value)
```
    Adds an attribute to the span. This can be used to add extra information to the span, which can be used by the APM tooling to provide more information about the span.
    
    Parameters:
    
    key - The key of the attribute.
    
    value - The value of the attribute.
    
    Returns:
    
    The span for fluent interfacing.

Interface Span

Method Summary

Method Detail

start

makeCurrent

end

recordException

run

wrapRunnable

runCallable

wrapCallable

runSupplier

wrapSupplier

runConsumer

wrapConsumer

addAttribute