io.opentracing

Interface Span

public interface Span

Span represents the OpenTracing specification's Span contract.

See Also:

Scope, ScopeManager, Tracer.SpanBuilder.start(), Tracer.SpanBuilder#startActive()

Method Summary

Modifier and Type	Method and Description
SpanContext	context() Retrieve the associated SpanContext.
void	finish() Sets the end timestamp to now and records the span.
void	finish(long finishMicros) Sets an explicit end timestamp and records the span.
String	getBaggageItem(String key)
Span	log(long timestampMicroseconds, Map<String,?> fields) Like log(Map<String, Object>), but with an explicit timestamp.
Span	log(long timestampMicroseconds, String event) Record an event at a specific timestamp.
Span	log(Map<String,?> fields) Log key:value pairs to the Span with the current walltime timestamp.
Span	log(String event) Record an event at the current walltime timestamp.
Span	setBaggageItem(String key, String value) Sets a baggage item in the Span (and its SpanContext) as a key/value pair.
Span	setOperationName(String operationName) Sets the string name for the logical operation this span represents.
Span	setTag(String key, boolean value) Same as setTag(String, String), but for boolean values.
Span	setTag(String key, Number value) Same as setTag(String, String), but for numeric values.
Span	setTag(String key, String value) Set a key:value tag on the Span.

Method Detail

context

SpanContext context()

Retrieve the associated SpanContext. This may be called at any time, including after calls to finish().

Returns:

the SpanContext that encapsulates Span state that should propagate across process boundaries.

setTag

Span setTag(String key,
            String value)

Set a key:value tag on the Span.

setTag

Span setTag(String key,
            boolean value)

Same as setTag(String, String), but for boolean values.

setTag

Span setTag(String key,
            Number value)

Same as setTag(String, String), but for numeric values.

log

Span log(Map<String,?> fields)

Log key:value pairs to the Span with the current walltime timestamp.

CAUTIONARY NOTE: not all Tracer implementations support key:value log fields end-to-end. Caveat emptor.

A contrived example (using Guava, which is not required):

     span.log(
     ImmutableMap.Builder()
     .put("event", "soft error")
     .put("type", "cache timeout")
     .put("waited.millis", 1500)
     .build());
     

Parameters:

fields - key:value log fields. Tracer implementations should support String, numeric, and boolean values; some may also support arbitrary Objects.

Returns:

the Span, for chaining

See Also:

log(String)

log

Span log(long timestampMicroseconds,
         Map<String,?> fields)

Like log(Map<String, Object>), but with an explicit timestamp.

CAUTIONARY NOTE: not all Tracer implementations support key:value log fields end-to-end. Caveat emptor.

Parameters:

timestampMicroseconds - The explicit timestamp for the log record. Must be greater than or equal to the Span's start timestamp.

fields - key:value log fields. Tracer implementations should support String, numeric, and boolean values; some may also support arbitrary Objects.

Returns:

the Span, for chaining

See Also:

log(long, String)

log

Span log(String event)

Record an event at the current walltime timestamp. Shorthand for

     span.log(Collections.singletonMap("event", event));
     

Parameters:

event - the event value; often a stable identifier for a moment in the Span lifecycle

Returns:

the Span, for chaining

log

Span log(long timestampMicroseconds,
         String event)

Record an event at a specific timestamp. Shorthand for

     span.log(timestampMicroseconds, Collections.singletonMap("event", event));
     

Parameters:

timestampMicroseconds - The explicit timestamp for the log record. Must be greater than or equal to the Span's start timestamp.

event - the event value; often a stable identifier for a moment in the Span lifecycle

Returns:

the Span, for chaining

setBaggageItem

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

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

setOperationName

Span setOperationName(String operationName)

Sets the string name for the logical operation this span represents.

Returns:

this Span instance, for chaining

finish

void finish()

Sets the end timestamp to now and records the span.

With the exception of calls to context(), this should be the last call made to the span instance. Future calls to finish() are defined as noops, and future calls to methods other than context() lead to undefined behavior.

See Also:

context()

finish

void finish(long finishMicros)

Sets an explicit end timestamp and records the span.

With the exception of calls to Span.context(), this should be the last call made to the span instance, and to do otherwise leads to undefined behavior.

Parameters:

finishMicros - an explicit finish time, in microseconds since the epoch

See Also:

context()