public interface Span
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.
For more information about creating different kinds of traces.
Modifier and Type | Method and Description |
---|---|
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)
|
default <T> Consumer<T> |
wrapConsumer(Consumer<T> supplier)
Wraps a
Consumer , tracing the invocation. |
default Runnable |
wrapRunnable(Runnable runnable)
|
default <T> Supplier<T> |
wrapSupplier(Supplier<T> supplier)
Wraps a
Supplier , tracing the invocation. |
Span start()
makeCurrent()
in
order to do so.default SpanScope makeCurrent()
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.
void end()
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.
Span recordException(Throwable t)
t
- The exception to recorddefault void run(Runnable runnable)
Runnable
will be invoked instantly and synchronously.runnable
- The Runnable
to execute.default Runnable wrapRunnable(Runnable runnable)
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.runnable
- The Runnable
to wrapdefault <T> T runCallable(Callable<T> callable) throws Exception
Callable
will be invoked instantly and synchronously.default <T> Callable<T> wrapCallable(Callable<T> callable)
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.callable
- The Callable
to wrapdefault <T> T runSupplier(Supplier<T> supplier)
Supplier
will be invoked instantly and synchronously.supplier
- The Supplier
to execute.default <T> Supplier<T> wrapSupplier(Supplier<T> supplier)
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.supplier
- The Supplier
to wrapdefault <T> void runConsumer(Consumer<T> supplier, T consumedObject)
Consumer
will be invoked instantly and synchronously.supplier
- The Consumer
to execute.default <T> Consumer<T> wrapConsumer(Consumer<T> supplier)
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.supplier
- The Consumer
to wrapCopyright © 2010–2023. All rights reserved.