Package brave.propagation

Class TraceContext

java.lang.Object

brave.propagation.SamplingFlags

brave.propagation.TraceContext

public final class TraceContext
extends SamplingFlags

Contains trace identifiers and sampling data propagated in and out-of-process.

Particularly, this includes trace identifiers and sampled state.

The implementation was originally com.github.kristofa.brave.SpanId, which was a port of com.twitter.finagle.tracing.TraceId. Unlike these mentioned, this type does not expose a single binary representation. That's because propagation forms can now vary.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TraceContext.Builder
static interface	TraceContext.Extractor<C>	Used to continue an incoming trace.
static interface	TraceContext.Injector<C>	Used to send the trace context downstream.

Field Summary

Fields inherited from class brave.propagation.SamplingFlags

DEBUG, EMPTY, NOT_SAMPLED, SAMPLED

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object o)	Includes mandatory fields traceIdHigh(), traceId(), spanId() and the shared flag.
List<Object>	extra()	Returns a list of additional data propagated through this trace.
<T> T	findExtra(Class<T> type)	Returns an extra of the given type if present or null if not.
int	hashCode()	Includes mandatory fields traceIdHigh(), traceId(), spanId() and the shared flag.
static TraceContext.Builder	newBuilder()
Long	parentId()	The parent's spanId or null if this the root span in a trace.
long	parentIdAsLong()	Like parentId() except returns a primitive where zero implies absent.
boolean	shared()	True if we are contributing to a span started by another tracer (ex on a different host).
long	spanId()	Unique 8-byte identifier of this span within a trace.
TraceContext.Builder	toBuilder()
String	toString()	Returns $traceId/$spanId
long	traceId()	Unique 8-byte identifier for a trace, set on all spans within it.
long	traceIdHigh()	When non-zero, the trace containing this span uses 128-bit trace identifiers.
String	traceIdString()	Returns the hex representation of the span's trace ID

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from class brave.propagation.SamplingFlags

build, debug, sampled

Method Detail

newBuilder

public static TraceContext.Builder newBuilder()

traceIdHigh

public long traceIdHigh()

When non-zero, the trace containing this span uses 128-bit trace identifiers.

traceId

public long traceId()

Unique 8-byte identifier for a trace, set on all spans within it.

parentId

@Nullable
public final Long parentId()

The parent's spanId or null if this the root span in a trace.

See Also:

parentIdAsLong()

parentIdAsLong

public long parentIdAsLong()

Like parentId() except returns a primitive where zero implies absent.

Using this method will avoid allocation, so is encouraged when copying data.

spanId

public long spanId()

Unique 8-byte identifier of this span within a trace.

A span is uniquely identified in storage by (traceId, spanId).

shared

public boolean shared()

True if we are contributing to a span started by another tracer (ex on a different host). Defaults to false.

Impact on indexing

When an RPC trace is client-originated, it will be sampled and the same span ID is used for the server side. The shared flag helps prioritize timestamp and duration indexing in favor of the client. In v1 format, there is no shared flag, so it implies converters should not store timestamp and duration on the server span explicitly.

extra

public List<Object> extra()

Returns a list of additional data propagated through this trace.

The contents are intentionally opaque, deferring to Propagation to define. An example implementation could be storing a class containing a correlation value, which is extracted from incoming requests and injected as-is onto outgoing requests.

Implementations are responsible for scoping any data stored here. This can be performed when Propagation.Factory.decorate(TraceContext) is called.

findExtra

@Nullable
public <T> T findExtra(Class<T> type)

Returns an extra of the given type if present or null if not.

Note: it is the responsibility of Propagation.Factory.decorate(TraceContext) to consolidate extra fields. If it doesn't, there could be multiple instance of a given type and this can break logic.

toBuilder

public TraceContext.Builder toBuilder()

traceIdString

public String traceIdString()

Returns the hex representation of the span's trace ID

toString

public String toString()

Returns $traceId/$spanId

Overrides:

toString in class SamplingFlags

equals

public boolean equals(Object o)

Includes mandatory fields traceIdHigh(), traceId(), spanId() and the shared flag.

The shared flag is included to have parity with the hashCode().

Overrides:

equals in class Object

hashCode

public int hashCode()

Includes mandatory fields traceIdHigh(), traceId(), spanId() and the shared flag.

The shared flag is included in the hash code to ensure loopback span data are partitioned properly. For example, if a client calls itself, the server-side shouldn't overwrite the client side.

Overrides:

hashCode in class Object