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

Nested Class Summary

Nested Classes

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

Method Summary

Modifier and Type	Method and Description
List<Annotation>	annotations() Events that explain latency with a timestamp.
Boolean	debug() True is a request to store this span even if it overrides sampling policy.
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(Object o)
int	hashCode()
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.
String	localServiceName()
String	name() Span name in lowercase, rpc method for example.
static Span.Builder	newBuilder()
static String	normalizeTraceId(String traceId) Returns a valid lower-hex trace ID, padded left as needed to 16 or 32 characters.
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.
String	remoteServiceName()
Boolean	shared() True if we are contributing to a span started by another tracer (ex on a different host).
Map<String,String>	tags() Tags a span with context, usually to support query or aggregation.
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()
String	toString()
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 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