Package brave.propagation

Class CurrentTraceContext

java.lang.Object

brave.propagation.CurrentTraceContext

Direct Known Subclasses:

StrictCurrentTraceContext, ThreadLocalCurrentTraceContext

public abstract class CurrentTraceContext
extends Object

This makes a given span the current span by placing it in scope (usually but not always a thread local scope).

This type is an SPI, and intended to be used by implementors looking to change thread-local storage, or integrate with other contexts such as logging (MDC).

Design

This design was inspired by com.google.instrumentation.trace.ContextUtils, com.google.inject.servlet.RequestScoper and com.github.kristofa.brave.CurrentSpan

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	CurrentTraceContext.Builder	Implementations of this allow standardized configuration, for example scope decoration.
static class	CurrentTraceContext.Default	Default implementation which is backed by a static thread local.
static interface	CurrentTraceContext.Scope	A span remains in the scope it was bound to until close is called.
static interface	CurrentTraceContext.ScopeDecorator	Use this to add features such as thread checks or log correlation when a scope is created or closed.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CurrentTraceContext()
protected	CurrentTraceContext(CurrentTraceContext.Builder builder)

Method Summary

Modifier and Type	Method	Description
protected CurrentTraceContext.Scope	decorateScope(TraceContext context, CurrentTraceContext.Scope scope)	When implementing newScope(TraceContext), decorate the result before returning it.
Executor	executor(Executor delegate)	Decorates the input such that the current trace context at the time a task is scheduled is made current when the task is executed.
ExecutorService	executorService(ExecutorService delegate)	Decorates the input such that the current trace context at the time a task is scheduled is made current when the task is executed.
abstract TraceContext	get()	Returns the current span in scope or null if there isn't one.
CurrentTraceContext.Scope	maybeScope(TraceContext context)	Like newScope(TraceContext), except returns CurrentTraceContext.Scope.NOOP if the given context is already in scope.
abstract CurrentTraceContext.Scope	newScope(TraceContext context)	Sets the current span in scope until the returned object is closed.
Runnable	wrap(Runnable task)	Wraps the input so that it executes with the same context as now.
<C> Callable<C>	wrap(Callable<C> task)	Wraps the input so that it executes with the same context as now.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CurrentTraceContext

protected CurrentTraceContext()

CurrentTraceContext

protected CurrentTraceContext(CurrentTraceContext.Builder builder)

Method Detail

get

@Nullable
public abstract TraceContext get()

Returns the current span in scope or null if there isn't one.

newScope

public abstract CurrentTraceContext.Scope newScope(@Nullable
                                                   TraceContext context)

Sets the current span in scope until the returned object is closed. It is a programming error to drop or never close the result. Using try-with-resources is preferred for this reason.

Parameters:

context - span to place into scope or null to clear the scope

decorateScope

protected CurrentTraceContext.Scope decorateScope(@Nullable
                                                  TraceContext context,
                                                  CurrentTraceContext.Scope scope)

When implementing newScope(TraceContext), decorate the result before returning it.

Ex.

{@code

Parameters:

scope - CurrentTraceContext.Scope.NOOP if the prior context was equal to the context parameter.

maybeScope

public CurrentTraceContext.Scope maybeScope(@Nullable
                                            TraceContext context)

Like newScope(TraceContext), except returns CurrentTraceContext.Scope.NOOP if the given context is already in scope. This can reduce overhead when scoping callbacks. However, this will not apply any changes, notably in TraceContext.extra(). As such, it should be used carefully and only in conditions where redundancy is possible and the intent is primarily to facilitate Tracer.currentSpan(). Most often, this is used to eliminate redundant scopes by wrappers.

For example, RxJava includes hooks to wrap types that represent an asynchronous functional composition. For example, flowable.parallel().flatMap(Y).sequential() Assembly hooks can ensure each stage of this operation can see the initial trace context. However, other tools can also instrument the stages, including vert.x or even agent instrumentation. When wrapping callbacks, it can reduce overhead to use maybeScope as opposed to newScope.

Generally speaking, this is best used for wrappers, such as executor services or lifecycle hooks, which usually have no current trace context when invoked.

Implementors note

For those overriding this method, you must compare TraceContext.traceIdHigh(), TraceContext.traceId() and TraceContext.spanId() to decide if the contexts are equivalent. Due to details of propagation, other data like parent ID are not considered in equivalence checks.

Parameters:

context - span to place into scope or null to clear the scope

Returns:

a new scope object or CurrentTraceContext.Scope.NOOP if the input is already the case

wrap

public <C> Callable<C> wrap(Callable<C> task)

Wraps the input so that it executes with the same context as now.

wrap

public Runnable wrap(Runnable task)

Wraps the input so that it executes with the same context as now.

executor

public Executor executor(Executor delegate)

Decorates the input such that the current trace context at the time a task is scheduled is made current when the task is executed.

executorService

public ExecutorService executorService(ExecutorService delegate)

Decorates the input such that the current trace context at the time a task is scheduled is made current when the task is executed.