Package org.axonframework.messaging.tracing

Interface Span

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:

  • Method Details

    • 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.

    • runSupplierAsync

      default <T> CompletableFuture<T> runSupplierAsync(Supplier<CompletableFuture<T>> supplier)

    • 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.