Span (Spring Cloud Sleuth Core 1.2.0.RELEASE API)

java.lang.Object
- org.springframework.cloud.sleuth.Span

All Implemented Interfaces:

SpanContext
```
public class Span
extends Object
implements SpanContext
```
Class for gathering and reporting statistics about a block of execution.
Spans should form a directed acyclic graph structure. It should be possible to keep following the parents of a span until you arrive at a span with no parents.
Spans can be either annotated with tags or logs.
An Annotation is used to record existence of an event in time. Below you can find some of the core annotations used to define the start and stop of a request:
- cs - Client Sent
- sr - Server Received
- ss - Server Sent
- cr - Client Received
Spring Cloud Sleuth uses Zipkin compatible header names
- X-B3-TraceId: 64 encoded bits
- X-B3-SpanId: 64 encoded bits
- X-B3-ParentSpanId: 64 encoded bits
- X-B3-Sampled: Boolean (either “1” or “0”)
Since:

1.0.0

Author:

Spencer Gibb, Marcin Grzejszczak

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Span.SpanBuilder

Nested Classes
Modifier and Type	Class and Description
`static class`	`Span.SpanBuilder`

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CLIENT_RECV` cr - Client Receive.
`static String`	`CLIENT_SEND` cs - Client Sent.
`static String`	`INSTANCEID` ID of the instance from which the span was originated.
`static String`	`PARENT_ID_NAME`
`static String`	`PROCESS_ID_NAME`
`static String`	`SAMPLED_NAME`
`static String`	`SERVER_RECV` sr - Server Receive.
`static String`	`SERVER_SEND` ss - Server Send.
`static String`	`SPAN_BAGGAGE_HEADER_PREFIX`
`static String`	`SPAN_ERROR_TAG_NAME`
`static String`	`SPAN_EXPORT_NAME`
`static String`	`SPAN_FLAGS`
`static Set<String>`	`SPAN_HEADERS`
`static String`	`SPAN_ID_NAME`
`static String`	`SPAN_LOCAL_COMPONENT_TAG_NAME`
`static String`	`SPAN_NAME_NAME`
`static String`	`SPAN_NOT_SAMPLED`
`static String`	`SPAN_PEER_SERVICE_TAG_NAME` As in Open Tracing
`static String`	`SPAN_SAMPLED`
`static String`	`TRACE_ID_NAME`

Constructor Summary

Constructors
Constructor and Description
`Span(long begin, long end, String name, long traceId, List<Long> parents, long spanId, boolean remote, boolean exportable, String processId)` Deprecated. please use `Span.SpanBuilder`
`Span(long begin, long end, String name, long traceId, List<Long> parents, long spanId, boolean remote, boolean exportable, String processId, Span savedSpan)` Deprecated. please use `Span.SpanBuilder`
`Span(Span current, Span savedSpan)` Creates a new span that still tracks tags and logs of the current span.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`Iterable<Map.Entry<String,String>>`	`baggageItems()`
`static Span.SpanBuilder`	`builder()`
`boolean`	`equals(Object o)`
`long`	`getAccumulatedMicros()` Return the total amount of time elapsed since start was called, if running, or difference between stop and start, in microseconds.
`long`	`getAccumulatedMillis()` Deprecated. use `getAccumulatedMicros()` as it is more precise.
`Map<String,String>`	`getBaggage()`
`String`	`getBaggageItem(String key)`
`long`	`getBegin()` Get the start time, in milliseconds
`long`	`getEnd()` Get the stop time, in milliseconds
`String`	`getName()` A human-readable name assigned to this span instance.
`List<Long>`	`getParents()` Returns the parent IDs of the span.
`String`	`getProcessId()` Return a unique id for the process from which this span originated.
`Span`	`getSavedSpan()` Returns the saved span.
`long`	`getSpanId()` A pseudo-unique (random) number assigned to this span instance.
`long`	`getTraceId()` Unique 8-byte identifier for a trace, set on all spans within it.
`long`	`getTraceIdHigh()` When non-zero, the trace containing this span uses 128-bit trace identifiers.
`int`	`hashCode()`
`boolean`	`hasSavedSpan()`
`static long`	`hexToId(String hexString)` Parses a 1 to 32 character lower-hex string with no prefix into an unsigned long, tossing any bits higher than 64.
`static long`	`hexToId(String lowerHex, int index)` Parses a 16 character lower-hex string with no prefix into an unsigned long, starting at the specified index.
`static String`	`idToHex(long id)` Represents given long id as 16-character lower-hex string
`boolean`	`isExportable()` Is the span eligible for export? If not then we may not need accumulate annotations (for instance).
`boolean`	`isRemote()` Flag that tells us whether the span was started in another process.
`boolean`	`isRunning()` Has the span been started and not yet stopped?
`void`	`logEvent(long timestampMilliseconds, String event)` Add a `event` to a specific point (a timestamp in milliseconds) in the timeline associated with this span.
`void`	`logEvent(String event)` Add an `event` to the timeline associated with this span.
`List<Log>`	`logs()` Get any timestamped events (read only) Will never be null.
`Span`	`setBaggageItem(String key, String value)` Sets a baggage item in the Span (and its SpanContext) as a key/value pair.
`void`	`stop()` The block has completed, stop the clock
`void`	`tag(String key, String value)` Add a tag or data annotation associated with this span.
`Map<String,String>`	`tags()` Get tag data associated with this span (read only) Will never be null.
`String`	`toString()`
`String`	`traceIdString()` Returns the 16 or 32 character 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
  - SAMPLED_NAME
```
public static final String SAMPLED_NAME
```
    See Also:
    
    Constant Field Values
  - PROCESS_ID_NAME
```
public static final String PROCESS_ID_NAME
```
    See Also:
    
    Constant Field Values
  - PARENT_ID_NAME
```
public static final String PARENT_ID_NAME
```
    See Also:
    
    Constant Field Values
  - TRACE_ID_NAME
```
public static final String TRACE_ID_NAME
```
    See Also:
    
    Constant Field Values
  - SPAN_NAME_NAME
```
public static final String SPAN_NAME_NAME
```
    See Also:
    
    Constant Field Values
  - SPAN_ID_NAME
```
public static final String SPAN_ID_NAME
```
    See Also:
    
    Constant Field Values
  - SPAN_EXPORT_NAME
```
public static final String SPAN_EXPORT_NAME
```
    See Also:
    
    Constant Field Values
  - SPAN_FLAGS
```
public static final String SPAN_FLAGS
```
    See Also:
    
    Constant Field Values
  - SPAN_BAGGAGE_HEADER_PREFIX
```
public static final String SPAN_BAGGAGE_HEADER_PREFIX
```
    See Also:
    
    Constant Field Values
  - SPAN_HEADERS
```
public static final Set<String> SPAN_HEADERS
```
  - SPAN_SAMPLED
```
public static final String SPAN_SAMPLED
```
    See Also:
    
    Constant Field Values
  - SPAN_NOT_SAMPLED
```
public static final String SPAN_NOT_SAMPLED
```
    See Also:
    
    Constant Field Values
  - SPAN_LOCAL_COMPONENT_TAG_NAME
```
public static final String SPAN_LOCAL_COMPONENT_TAG_NAME
```
    See Also:
    
    Constant Field Values
  - SPAN_ERROR_TAG_NAME
```
public static final String SPAN_ERROR_TAG_NAME
```
    See Also:
    
    Constant Field Values
  - CLIENT_RECV
```
public static final String CLIENT_RECV
```
    cr - Client Receive. Signifies the end of the span. The client has successfully received the response from the server side. If one subtracts the cs timestamp from this timestamp one will receive the whole time needed by the client to receive the response from the server.
    
    See Also:
    
    Constant Field Values
  - CLIENT_SEND
```
public static final String CLIENT_SEND
```
    cs - Client Sent. The client has made a request (a client can be e.g. RestTemplate. This annotation depicts the start of the span.
    
    See Also:
    
    Constant Field Values
  - SERVER_RECV
```
public static final String SERVER_RECV
```
    sr - Server Receive. The server side got the request and will start processing it. If one subtracts the cs timestamp from this timestamp one will receive the network latency.
    
    See Also:
    
    Constant Field Values
  - SERVER_SEND
```
public static final String SERVER_SEND
```
    ss - Server Send. Annotated upon completion of request processing (when the response got sent back to the client). If one subtracts the sr timestamp from this timestamp one will receive the time needed by the server side to process the request.
    
    See Also:
    
    Constant Field Values
  - SPAN_PEER_SERVICE_TAG_NAME
```
public static final String SPAN_PEER_SERVICE_TAG_NAME
```
    As in Open Tracing
    
    See Also:
    
    Constant Field Values
  - INSTANCEID
```
public static final String INSTANCEID
```
    ID of the instance from which the span was originated.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Span
```
public Span(Span current,
            Span savedSpan)
```
    Creates a new span that still tracks tags and logs of the current span. This is crucial when continuing spans since the changes in those collections done in the continued span need to be reflected until the span gets closed.
  - Span
```
@Deprecated
public Span(long begin,
                        long end,
                        String name,
                        long traceId,
                        List<Long> parents,
                        long spanId,
                        boolean remote,
                        boolean exportable,
                        String processId)
```
    Deprecated. please use Span.SpanBuilder
  - Span
```
@Deprecated
public Span(long begin,
                        long end,
                        String name,
                        long traceId,
                        List<Long> parents,
                        long spanId,
                        boolean remote,
                        boolean exportable,
                        String processId,
                        Span savedSpan)
```
    Deprecated. please use Span.SpanBuilder
- Method Detail
  - builder
```
public static Span.SpanBuilder builder()
```
  - stop
```
public void stop()
```
    The block has completed, stop the clock
  - getAccumulatedMillis
```
@Deprecated
public long getAccumulatedMillis()
```
    Deprecated. use getAccumulatedMicros() as it is more precise.
    
    Return the total amount of time elapsed since start was called, if running, or difference between stop and start
  - getAccumulatedMicros
```
public long getAccumulatedMicros()
```
    Return the total amount of time elapsed since start was called, if running, or difference between stop and start, in microseconds. Note that in case of the spans that have CS / CR events we will not send to Zipkin the accumulated microseconds but will calculate the duration basing on the timestamps of the CS / CR events.
    
    Returns:
    
    zero if not running, or a positive number of microseconds.
  - isRunning
```
public boolean isRunning()
```
    Has the span been started and not yet stopped?
  - tag
```
public void tag(String key,
                String value)
```
    Add a tag or data annotation associated with this span. The tag will be added only if it has a value.
  - logEvent
```
public void logEvent(String event)
```
    Add an event to the timeline associated with this span.
  - logEvent
```
public void logEvent(long timestampMilliseconds,
                     String event)
```
    Add a event to a specific point (a timestamp in milliseconds) in the timeline associated with this span.
  - setBaggageItem
```
public Span setBaggageItem(String key,
                           String value)
```
    Sets a baggage item in the Span (and its SpanContext) as a key/value pair. Baggage enables powerful distributed context propagation functionality where arbitrary application data can be carried along the full path of request execution throughout the system. Note 1: Baggage is only propagated to the future (recursive) children of this SpanContext. Note 2: Baggage is sent in-band with every subsequent local and remote calls, so this feature must be used with care.
    
    Returns:
    
    this Span instance, for chaining
  - getBaggageItem
```
public String getBaggageItem(String key)
```
    Returns:
    
    the value of the baggage item identified by the given key, or null if no such item could be found
  - baggageItems
```
public final Iterable<Map.Entry<String,String>> baggageItems()
```
    Specified by:
    
    baggageItems in interface SpanContext
    
    Returns:
    
    all zero or more baggage items propagating along with the associated Span
    
    See Also:
    
    setBaggageItem(String, String), getBaggageItem(String)
  - getBaggage
```
public final Map<String,String> getBaggage()
```
  - tags
```
public Map<String,String> tags()
```
    Get tag data associated with this span (read only)
    
    Will never be null.
  - logs
```
public List<Log> logs()
```
    Get any timestamped events (read only)
    
    Will never be null.
  - getSavedSpan
```
public Span getSavedSpan()
```
    Returns the saved span. The one that was "current" before this span.
    Might be null
  - hasSavedSpan
```
public boolean hasSavedSpan()
```
  - getName
```
public String getName()
```
    A human-readable name assigned to this span instance.
  - getSpanId
```
public long getSpanId()
```
    A pseudo-unique (random) number assigned to this span instance.
    
    The span id is immutable and cannot be changed. It is safe to access this from multiple threads.
  - getTraceIdHigh
```
public long getTraceIdHigh()
```
    When non-zero, the trace containing this span uses 128-bit trace identifiers.
    traceIdHigh corresponds to the high bits in big-endian format and getTraceId() 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.getTraceIdHigh());
 traceId128.putLong(span.getTraceId());
 traceBytes = traceId128.array();
 
```
    Since:
    
    1.0.11
    
    See Also:
    
    traceIdString()
  - getTraceId
```
public long getTraceId()
```
    Unique 8-byte identifier for a trace, set on all spans within it.
    
    See Also:
    
    for notes about 128-bit trace identifiers
  - getProcessId
```
public String getProcessId()
```
    Return a unique id for the process from which this span originated.
    Might be null
  - getParents
```
public List<Long> getParents()
```
    Returns the parent IDs of the span.
    
    The collection will be empty if there are no parents.
  - isRemote
```
public boolean isRemote()
```
    Flag that tells us whether the span was started in another process. Useful in RPC tracing when the receiver actually has to add annotations to the senders span.
  - getBegin
```
public long getBegin()
```
    Get the start time, in milliseconds
  - getEnd
```
public long getEnd()
```
    Get the stop time, in milliseconds
  - isExportable
```
public boolean isExportable()
```
    Is the span eligible for export? If not then we may not need accumulate annotations (for instance).
  - traceIdString
```
public String traceIdString()
```
    Returns the 16 or 32 character hex representation of the span's trace ID
    
    Since:
    
    1.0.11
  - idToHex
```
public static String idToHex(long id)
```
    Represents given long id as 16-character lower-hex string
    
    See Also:
    
    traceIdString()
  - hexToId
```
public static long hexToId(String hexString)
```
    Parses a 1 to 32 character lower-hex string with no prefix into an unsigned long, tossing any bits higher than 64.
  - hexToId
```
public static long hexToId(String lowerHex,
                           int index)
```
    Parses a 16 character lower-hex string with no prefix into an unsigned long, starting at the specified index.
    
    Since:
    
    1.0.11
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object

Class Span

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SAMPLED_NAME

PROCESS_ID_NAME

PARENT_ID_NAME

TRACE_ID_NAME

SPAN_NAME_NAME

SPAN_ID_NAME

SPAN_EXPORT_NAME

SPAN_FLAGS

SPAN_BAGGAGE_HEADER_PREFIX

SPAN_HEADERS

SPAN_SAMPLED

SPAN_NOT_SAMPLED

SPAN_LOCAL_COMPONENT_TAG_NAME

SPAN_ERROR_TAG_NAME

CLIENT_RECV

CLIENT_SEND

SERVER_RECV

SERVER_SEND

SPAN_PEER_SERVICE_TAG_NAME

INSTANCEID

Constructor Detail

Span

Span

Span

Method Detail

builder

stop

getAccumulatedMillis

getAccumulatedMicros

isRunning

tag

logEvent

logEvent

setBaggageItem

getBaggageItem

baggageItems

getBaggage

tags

logs

getSavedSpan

hasSavedSpan

getName

getSpanId

getTraceIdHigh

getTraceId

getProcessId

getParents

isRemote

getBegin

getEnd

isExportable

traceIdString

idToHex

hexToId

hexToId

toString

hashCode

equals