Package zipkin2

Class Span

  • All Implemented Interfaces:
    java.io.Serializable
    public final class Span
extends java.lang.Object
implements java.io.Serializable
    A span is a single-host view of an operation. A trace is a series of spans (often RPC calls) which nest to form a latency tree. Spans are in the same trace when they share the same trace ID. The parentId field establishes the position of one span in the tree.

    The root span is where parentId is null and usually has the longest duration in the trace. However, nested asynchronous work can materialize as child spans whose duration exceed the root span.

    Spans usually represent remote activity such as RPC calls, or messaging producers and consumers. However, they can also represent in-process activity in any position of the trace. For example, a root span could represent a server receiving an initial client request. A root span could also represent a scheduled job that has no remote context.

    While span identifiers are packed into longs, they should be treated opaquely. ID encoding is 16 or 32 character lower-hex, to avoid signed interpretation.

    Relationship to zipkin.Span

    This type is intended to replace use of zipkin.Span. Particularly, tracers represent a single-host view of an operation. By making one endpoint implicit for all data, this type does not need to repeat endpoints on each data like zipkin.Span does. This results in simpler and smaller data.

    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Span.Builder  
      static class  Span.Kind
      Indicates the primary span type.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.List<Annotation> annotations()
      Events that explain latency with a timestamp.
      java.lang.Boolean debug()
      True is a request to store this span even if it overrides sampling policy.
      java.lang.Long duration()
      Measurement in microseconds of the critical path, if known.
      long durationAsLong()
      Like duration() except returns a primitive where zero implies absent.
      boolean equals​(java.lang.Object o)  
      int hashCode()  
      java.lang.String id()
      Unique 64bit identifier for this operation within the trace.
      Span.Kind kind()
      When present, used to interpret remoteEndpoint
      Endpoint localEndpoint()
      The host that recorded this span, primarily for query by service name.
      java.lang.String localServiceName()  
      java.lang.String name()
      Span name in lowercase, rpc method for example.
      static Span.Builder newBuilder()  
      static java.lang.String normalizeTraceId​(java.lang.String traceId)
      Returns a valid lower-hex trace ID, padded left as needed to 16 or 32 characters.
      java.lang.String parentId()
      The parent's id or null if this the root span in a trace.
      Endpoint remoteEndpoint()
      When an RPC (or messaging) span, indicates the other side of the connection.
      java.lang.String remoteServiceName()  
      java.lang.Boolean shared()
      True if we are contributing to a span started by another tracer (ex on a different host).
      java.util.Map<java.lang.String,​java.lang.String> tags()
      Tags a span with context, usually to support query or aggregation.
      java.lang.Long timestamp()
      Epoch microseconds of the start of this span, possibly absent if this an incomplete span.
      long timestampAsLong()
      Like timestamp() except returns a primitive where zero implies absent.
      Span.Builder toBuilder()  
      java.lang.String toString()  
      java.lang.String traceId()
      Trace identifier, set on all spans within it.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • traceId

        public java.lang.String traceId()
        Trace identifier, set on all spans within it.

        Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits. For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3.

        Some systems downgrade trace identifiers to 64bit by dropping the left-most 16 characters. For example, 4e441824ec2b6a44ffdc9bb9a6453df3 becomes ffdc9bb9a6453df3.

      • parentId

        @Nullable
public java.lang.String parentId()
        The parent's id or null if this the root span in a trace.

        This is the same encoding as id. For example ffdc9bb9a6453df3

      • id

        public java.lang.String id()
        Unique 64bit identifier for this operation within the trace.

        Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3

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

      • name

        @Nullable
public java.lang.String name()
        Span name in lowercase, rpc method for example.

        Conventionally, when the span name isn't known, name = "unknown".

      • timestamp

        @Nullable
public java.lang.Long timestamp()
        Epoch microseconds of the start of this span, possibly absent if this an incomplete span.

        This value should be set directly by instrumentation, using the most precise value possible. For example, gettimeofday or multiplying System.currentTimeMillis() by 1000.

        There are three known edge-cases where this could be reported absent: 

          
 
        • A span was allocated but never started (ex not yet received a timestamp)
          • 
 
        • The span's start event was lost
          • 
 
        • Data about a completed span (ex tags) were sent after the fact
          •

          Note: timestamps at or before epoch (0L == 1970) are invalid

        See Also:
        duration(), timestampAsLong()

      • timestampAsLong

        public long timestampAsLong()
        Like timestamp() except returns a primitive where zero implies absent.

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

      • duration

        @Nullable
public java.lang.Long duration()
        Measurement in microseconds of the critical path, if known. Durations of less than one microsecond must be rounded up to 1 microsecond.

        This value should be set directly, as opposed to implicitly via annotation timestamps. Doing so encourages precision decoupled from problems of clocks, such as skew or NTP updates causing time to move backwards.

        If this field is persisted as unset, zipkin will continue to work, except duration query support will be implementation-specific. Similarly, setting this field non-atomically is implementation-specific.

        This field is i64 vs i32 to support spans longer than 35 minutes.

        See Also:
        durationAsLong()

      • durationAsLong

        public long durationAsLong()
        Like duration() except returns a primitive where zero implies absent.

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

      • localEndpoint

        @Nullable
public Endpoint localEndpoint()
        The host that recorded this span, primarily for query by service name.

        Instrumentation should always record this and be consistent as possible with the service name as it is used in search. This is nullable for legacy reasons.

      • remoteEndpoint

        @Nullable
public Endpoint remoteEndpoint()
        When an RPC (or messaging) span, indicates the other side of the connection.

        By recording the remote endpoint, your trace will contain network context even if the peer is not tracing. For example, you can record the IP from the X-Forwarded-For header or the service name and socket of a remote peer.

      • annotations

        public java.util.List<Annotation> annotations()
        Events that explain latency with a timestamp. Unlike log statements, annotations are often short or contain codes: for example "brave.flush". Annotations are sorted ascending by timestamp.

      • tags

        public java.util.Map<java.lang.String,​java.lang.String> tags()
        Tags a span with context, usually to support query or aggregation.

        For example, a tag key could be "http.path".

      • debug

        @Nullable
public java.lang.Boolean debug()
        True is a request to store this span even if it overrides sampling policy.

      • shared

        @Nullable
public java.lang.Boolean shared()
        True if we are contributing to a span started by another tracer (ex on a different host). Defaults to null. When set, it is expected for kind() to be Span.Kind.SERVER.

        When an RPC trace is client-originated, it will be sampled and the same span ID is used for the server side. However, the server shouldn't set span.timestamp or duration since it didn't start the span.

      • localServiceName

        @Nullable
public java.lang.String localServiceName()

      • remoteServiceName

        @Nullable
public java.lang.String remoteServiceName()

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • normalizeTraceId

        public static java.lang.String normalizeTraceId​(java.lang.String traceId)
        Returns a valid lower-hex trace ID, padded left as needed to 16 or 32 characters.
        Throws:
        java.lang.IllegalArgumentException - if oversized or not lower-hex

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object