Package zipkin2.proto3

Class Span

  • All Implemented Interfaces:
    java.io.Serializable
    public final class Span
extends com.squareup.wire.Message<Span,​Span.Builder>
    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 parent_id field establishes the position of one span in the tree. The root span is where parent_id is Absent 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. Encoding notes: Epoch timestamp are encoded fixed64 as varint would also be 8 bytes, and more expensive to encode and size. Duration is stored uint64, as often the numbers are quite small. Default values are ok, as only natural numbers are used. For example, zero is an invalid timestamp and an invalid duration, false values for debug or shared are ignorable, and zero-length strings also coerce to null. The next id is 14. Note fields up to 15 take 1 byte to encode. Take care when adding new fields https://developers.google.com/protocol-buffers/docs/proto3#assigning-tags
    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Span.Builder  
      static class  Span.Kind
      When present, kind clarifies timestamp, duration and remote_endpoint.

      • Nested classes/interfaces inherited from class com.squareup.wire.Message

        com.squareup.wire.Message.Companion

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static com.squareup.wire.ProtoAdapter<Span> ADAPTER  
      java.util.List<Annotation> annotations
      Associates events that explain latency with the time they happened.
      java.lang.Boolean debug
      True is a request to store this span even if it overrides sampling policy.
      static java.lang.Boolean DEFAULT_DEBUG  
      static java.lang.Long DEFAULT_DURATION  
      static okio.ByteString DEFAULT_ID  
      static Span.Kind DEFAULT_KIND  
      static java.lang.String DEFAULT_NAME  
      static okio.ByteString DEFAULT_PARENT_ID  
      static java.lang.Boolean DEFAULT_SHARED  
      static java.lang.Long DEFAULT_TIMESTAMP  
      static okio.ByteString DEFAULT_TRACE_ID  
      java.lang.Long duration
      Duration in microseconds of the critical path, if known.
      okio.ByteString id
      Unique identifier for this operation within the trace.
      Span.Kind kind
      When present, used to interpret remote_endpoint
      Endpoint local_endpoint
      The host that recorded this span, primarily for query by service name.
      java.lang.String name
      The logical operation this span represents in lowercase (e.g.
      okio.ByteString parent_id
      The parent span ID or absent if this the root span in a trace.
      Endpoint remote_endpoint
      When an RPC (or messaging) span, indicates the other side of the connection.
      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 give your span context for search, viewing and analysis.
      java.lang.Long timestamp
      Epoch microseconds of the start of this span, possibly absent if incomplete.
      okio.ByteString trace_id
      Randomly generated, unique identifier for a trace, set on all spans within it.

      • Fields inherited from class com.squareup.wire.Message

        Companion, hashCode

    • Constructor Summary

      Constructors 
      Constructor Description
      Span​(okio.ByteString trace_id, okio.ByteString parent_id, okio.ByteString id, Span.Kind kind, java.lang.String name, java.lang.Long timestamp, java.lang.Long duration, Endpoint local_endpoint, Endpoint remote_endpoint, java.util.List<Annotation> annotations, java.util.Map<java.lang.String,​java.lang.String> tags, java.lang.Boolean debug, java.lang.Boolean shared)  
      Span​(okio.ByteString trace_id, okio.ByteString parent_id, okio.ByteString id, Span.Kind kind, java.lang.String name, java.lang.Long timestamp, java.lang.Long duration, Endpoint local_endpoint, Endpoint remote_endpoint, java.util.List<Annotation> annotations, java.util.Map<java.lang.String,​java.lang.String> tags, java.lang.Boolean debug, java.lang.Boolean shared, okio.ByteString unknownFields)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object other)  
      int hashCode()  
      Span.Builder newBuilder()  
      java.lang.String toString()  

      • Methods inherited from class com.squareup.wire.Message

        adapter, encode, encode, encode, getCachedSerializedSize$wire_runtime, setCachedSerializedSize$wire_runtime, unknownFields, withoutUnknownFields, writeReplace

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • ADAPTER

        public static final com.squareup.wire.ProtoAdapter<Span> ADAPTER

      • DEFAULT_TRACE_ID

        public static final okio.ByteString DEFAULT_TRACE_ID

      • DEFAULT_PARENT_ID

        public static final okio.ByteString DEFAULT_PARENT_ID

      • DEFAULT_ID

        public static final okio.ByteString DEFAULT_ID

      • DEFAULT_KIND

        public static final Span.Kind DEFAULT_KIND

      • DEFAULT_TIMESTAMP

        public static final java.lang.Long DEFAULT_TIMESTAMP

      • DEFAULT_DURATION

        public static final java.lang.Long DEFAULT_DURATION

      • DEFAULT_DEBUG

        public static final java.lang.Boolean DEFAULT_DEBUG

      • DEFAULT_SHARED

        public static final java.lang.Boolean DEFAULT_SHARED

      • trace_id

        public final okio.ByteString trace_id
        Randomly generated, unique identifier for a trace, set on all spans within it. This field is required and encoded as 8 or 16 bytes, in big endian byte order.

      • parent_id

        public final okio.ByteString parent_id
        The parent span ID or absent if this the root span in a trace.

      • id

        public final okio.ByteString id
        Unique identifier for this operation within the trace. This field is required and encoded as 8 opaque bytes.

      • kind

        public final Span.Kind kind
        When present, used to interpret remote_endpoint

      • name

        public final java.lang.String name
        The logical operation this span represents in lowercase (e.g. rpc method). Leave absent if unknown. As these are lookup labels, take care to ensure names are low cardinality. For example, do not embed variables into the name.

      • timestamp

        public final java.lang.Long timestamp
        Epoch microseconds of the start of this span, possibly absent if incomplete. For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC This value should be set directly by instrumentation, using the most precise value possible. For example, gettimeofday or multiplying epoch millis 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

      • duration

        public final java.lang.Long duration
        Duration in microseconds of the critical path, if known. Durations of less than one are rounded up. Duration of children can be longer than their parents due to asynchronous operations. For example 150 milliseconds is 150000 microseconds.

      • local_endpoint

        public final Endpoint local_endpoint
        The host that recorded this span, primarily for query by service name. Instrumentation should always record this. Usually, absent implies late data. The IP address corresponding to this is usually the site local or advertised service address. When present, the port indicates the listen port.

      • remote_endpoint

        public final Endpoint remote_endpoint
        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 final java.util.List<Annotation> annotations
        Associates events that explain latency with the time they happened.

      • tags

        public final java.util.Map<java.lang.String,​java.lang.String> tags
        Tags give your span context for search, viewing and analysis. For example, a key "your_app.version" would let you lookup traces by version. A tag "sql.query" isn't searchable, but it can help in debugging when viewing a trace.

      • debug

        public final java.lang.Boolean debug
        True is a request to store this span even if it overrides sampling policy. This is true when the "X-B3-Flags" header has a value of 1.

      • shared

        public final java.lang.Boolean shared
        True if we are contributing to a span started by another tracer (ex on a different host).

    • Constructor Detail

      • Span

        public Span​(okio.ByteString trace_id,
            okio.ByteString parent_id,
            okio.ByteString id,
            Span.Kind kind,
            java.lang.String name,
            java.lang.Long timestamp,
            java.lang.Long duration,
            Endpoint local_endpoint,
            Endpoint remote_endpoint,
            java.util.List<Annotation> annotations,
            java.util.Map<java.lang.String,​java.lang.String> tags,
            java.lang.Boolean debug,
            java.lang.Boolean shared)

      • Span

        public Span​(okio.ByteString trace_id,
            okio.ByteString parent_id,
            okio.ByteString id,
            Span.Kind kind,
            java.lang.String name,
            java.lang.Long timestamp,
            java.lang.Long duration,
            Endpoint local_endpoint,
            Endpoint remote_endpoint,
            java.util.List<Annotation> annotations,
            java.util.Map<java.lang.String,​java.lang.String> tags,
            java.lang.Boolean debug,
            java.lang.Boolean shared,
            okio.ByteString unknownFields)

    • Method Detail

      • equals

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

      • hashCode

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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class com.squareup.wire.Message<Span,​Span.Builder>