Package brave.propagation

Class 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 Detail

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

      • 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

      • 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