io.zipkin

Class Span

java.lang.Object

io.zipkin.Span

All Implemented Interfaces:

Comparable<Span>

public final class Span
extends Object
implements Comparable<Span>

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. String encoding is fixed-width lower-hex, to avoid signed interpretation.

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.

Method Summary

Modifier and Type	Method and Description
int	compareTo(Span that) Compares by timestamp, then name.
boolean	equals(Object o)
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

traceId

public final long traceId

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

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 syncing System.nanoTime() against a tick of System.currentTimeMillis().

For compatibilty 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.

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.uri".

debug

@Nullable
public final Boolean debug

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

Method Detail

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>