Package zipkin2

Class Span

java.lang.Object
zipkin2.Span
All Implemented Interfaces:
Serializable
public final class Span
extends Object
implements 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

  • Method Details

    • traceId

      public 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 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 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()).

    • kind

      @Nullable public Span.Kind kind()
      When present, used to interpret remoteEndpoint

    • name

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

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

    • timestamp

      @Nullable public 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 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 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 Map<String,​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 Boolean debug()
      True is a request to store this span even if it overrides sampling policy.

    • shared

      @Nullable public 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 String localServiceName()

    • remoteServiceName

      @Nullable public String remoteServiceName()

    • newBuilder

      public static Span.Builder newBuilder()

    • toBuilder

      public Span.Builder toBuilder()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • normalizeTraceId

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

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object