Package brave.propagation

Class StrictCurrentTraceContext

java.lang.Object

brave.propagation.CurrentTraceContext

brave.propagation.StrictCurrentTraceContext

All Implemented Interfaces:

Closeable, AutoCloseable

public final class StrictCurrentTraceContext
extends CurrentTraceContext
implements Closeable

Useful when developing instrumentation as state is enforced more strictly.

For example, it is instance scoped as opposed to static scoped, not inheritable and throws an exception if a scope is closed on a different thread that it was opened on.

See Also:

StrictScopeDecorator

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	StrictCurrentTraceContext.Builder

Nested classes/interfaces inherited from class brave.propagation.CurrentTraceContext

CurrentTraceContext.Default, CurrentTraceContext.Scope, CurrentTraceContext.ScopeDecorator

Constructor Summary

Constructors

Constructor	Description
StrictCurrentTraceContext()

Method Summary

Modifier and Type	Method	Description
void	close()	Calls StrictScopeDecorator.close()
static StrictCurrentTraceContext	create()
TraceContext	get()	Returns the current span in scope or null if there isn't one.
CurrentTraceContext.Scope	maybeScope(TraceContext context)	Like CurrentTraceContext.newScope(TraceContext), except returns CurrentTraceContext.Scope.NOOP if the given context is already in scope.
static StrictCurrentTraceContext.Builder	newBuilder()
CurrentTraceContext.Scope	newScope(TraceContext context)	Sets the current span in scope until the returned object is closed.

Methods inherited from class brave.propagation.CurrentTraceContext

decorateScope, executor, executorService, wrap, wrap

Methods inherited from class java.lang.Object

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

Constructor Details

StrictCurrentTraceContext

public StrictCurrentTraceContext()

Method Details

create

public static StrictCurrentTraceContext create()

Since:

5.11

newBuilder

public static StrictCurrentTraceContext.Builder newBuilder()

Since:

5.11

get

public TraceContext get()

Description copied from class: CurrentTraceContext

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

Specified by:

get in class CurrentTraceContext

newScope

public CurrentTraceContext.Scope newScope(@Nullable TraceContext context)

Description copied from class: CurrentTraceContext

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.

Specified by:

newScope in class CurrentTraceContext

Parameters:

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

maybeScope

public CurrentTraceContext.Scope maybeScope(TraceContext context)

Description copied from class: CurrentTraceContext

Like CurrentTraceContext.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.

Overrides:

maybeScope in class CurrentTraceContext

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

close

public void close()

Calls StrictScopeDecorator.close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Since:

5.11