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. TheparentId
field establishes the position of one span in the tree.The root span is where
parentId
is null and usually has the longestduration
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 likezipkin.Span
does. This results in simpler and smaller data.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Span.Builder
static class
Span.Kind
Indicates the primary span type.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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()
Likeduration()
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 interpretremoteEndpoint
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'sid
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()
Liketimestamp()
except returns a primitive where zero implies absent.Span.Builder
toBuilder()
String
toString()
String
traceId()
Trace identifier, set on all spans within it.
-
-
-
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
becomesffdc9bb9a6453df3
.
-
parentId
@Nullable public String parentId()
-
id
public String id()
-
kind
@Nullable public Span.Kind kind()
When present, used to interpretremoteEndpoint
-
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 multiplyingSystem.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()
Liketimestamp()
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()
Likeduration()
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 forkind()
to beSpan.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()
-
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
-
-