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

  • Constructor Details

  • Method Details

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