zipkin

Class Span

java.lang.Object

zipkin.Span

All Implemented Interfaces:

Serializable, Comparable<Span>

public final class Span
extends Object
implements Comparable<Span>, Serializable

A trace is a series of spans (often RPC calls) which form a latency tree.

Spans are usually created by instrumentation in RPC clients or servers, but can also represent in-process activity. Annotations in spans are similar to log statements, and are sometimes created directly by application developers to indicate events of interest, such as a cache miss.

The root span is where parentId is null; it usually has the longest duration in the trace.

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

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Span.Builder

Field Summary

Fields

Modifier and Type	Field and Description
List<Annotation>	annotations Associates events that explain latency with a timestamp.
List<BinaryAnnotation>	binaryAnnotations Tags a span with context, usually to support query or aggregation.
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	id Unique 8-byte identifier of this span within a trace.
String	name Span name in lowercase, rpc method for example.
Long	parentId The parent's id or null if this the root span in a trace.
Long	timestamp Epoch microseconds of the start of this span, possibly absent if this an incomplete span.
long	traceId Unique 8-byte identifier for a trace, set on all spans within it.
long	traceIdHigh When non-zero, the trace containing this span uses 128-bit trace identifiers.

Method Summary

Modifier and Type	Method and Description
static Span.Builder	builder()
int	compareTo(Span that) Compares by timestamp, then name.
boolean	equals(Object o)
int	hashCode()
String	idString() Returns $traceId.$spanId<:$parentId or $spanId
Set<String>	serviceNames() Returns the distinct service names that logged to this span.
Span.Builder	toBuilder()
String	toString()
String	traceIdString() Returns the hex representation of the span's trace ID

Methods inherited from class java.lang.Object

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

Field Detail

traceIdHigh

public final long traceIdHigh

When non-zero, the trace containing this span uses 128-bit trace identifiers.

traceIdHigh corresponds to the high bits in big-endian format and traceId corresponds to the low bits.

Ex. to convert the two fields to a 128bit opaque id array, you'd use code like below.

 ByteBuffer traceId128 = ByteBuffer.allocate(16);
 traceId128.putLong(span.traceIdHigh);
 traceId128.putLong(span.traceId);
 traceBytes = traceId128.array();
 

See Also:

StorageComponent.Builder#strictTraceId(boolean)

traceId

public final long traceId

Unique 8-byte identifier for a trace, set on all spans within it.

See Also:

for notes about 128-bit trace identifiers

name

public final String name

Span name in lowercase, rpc method for example.

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

id

public final long id

Unique 8-byte identifier of this span within a trace.

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

parentId

@Nullable
public final Long parentId

The parent's id or null if this the root span in a trace.

timestamp

@Nullable
public final 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.

For compatibility with instrumentation that precede this field, collectors or span stores can derive this via Annotation.timestamp. For example, Constants.SERVER_RECV.timestamp or Constants.CLIENT_SEND.timestamp.

Timestamp is nullable for input only. Spans without a timestamp cannot be presented in a timeline: Span stores should not output spans missing a timestamp.

There are two known edge-cases where this could be absent: both cases exist when a collector receives a span in parts and a binary annotation precedes a timestamp. This is possible when..

• The span is in-flight (ex not yet received a timestamp)
• The span's start event was lost

duration

@Nullable
public final 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.

For compatibility with instrumentation that precede this field, collectors or span stores can derive this by subtracting Annotation.timestamp. For example, Constants.SERVER_SEND.timestamp - Constants.SERVER_RECV.timestamp.

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.

annotations

public final List<Annotation> annotations

Associates events that explain latency with a timestamp.

Unlike log statements, annotations are often codes: for example Constants.SERVER_RECV. Annotations are sorted ascending by timestamp.

binaryAnnotations

public final List<BinaryAnnotation> binaryAnnotations

Tags a span with context, usually to support query or aggregation.

example, a binary annotation key could be "http.path".

debug

@Nullable
public final Boolean debug

True is a request to store this span even if it overrides sampling policy.

Method Detail

toBuilder

public Span.Builder toBuilder()

builder

public static Span.Builder builder()

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(Span that)

Compares by timestamp, then name.

Specified by:

compareTo in interface Comparable<Span>

traceIdString

public String traceIdString()

Returns the hex representation of the span's trace ID

idString

public String idString()

Returns $traceId.$spanId<:$parentId or $spanId

serviceNames

public Set<String> serviceNames()

Returns the distinct service names that logged to this span.