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.

Since:
4.0

  • Method Details

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

    • localRootId

      public long localRootId()
      Returns the first spanId() in a partition of a trace: otherwise known as an entry span. This could be a root span or a span representing incoming work (ex Span.Kind.SERVER or Span.Kind.CONSUMER. Unlike parentIdAsLong(), this value is inherited to child contexts until the trace exits the process. This value is inherited for all child spans until the trace exits the process. This could also be described as an entry span.

      When isLocalRoot(), this ID will be the same as the span ID.

      The local root ID can be used for dependency link processing, skipping data or partitioning purposes. For example, one processor could skip all intermediate (local) spans between an incoming service call and any outgoing ones.

      This does not group together multiple points of entry in the same trace. For example, repetitive consumption of the same incoming message results in different local roots.

      Returns:
      the span ID of the local root or zero if this context wasn't initialized by a Tracer.

    • isLocalRoot

      public boolean isLocalRoot()

    • 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 recording a server span with the same span ID parsed from incoming headers.

      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.

      Since:
      4.9

    • findExtra

      @Nullable public <T> T findExtra​(Class<T> type)
      Returns a propagated state of the given type if present or null if not.

      Note: It is the responsibility of Propagation.Factory.decorate(TraceContext) to consolidate elements. If it doesn't, there could be multiple instances 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

    • parentIdString

      @Nullable public String parentIdString()
      Returns the hex representation of the span's parent ID

    • localRootIdString

      @Nullable public String localRootIdString()
      Returns the hex representation of the span's local root ID

    • spanIdString

      public String spanIdString()
      Returns the hex representation of the span's 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