io.opentracing

Interface BaseSpan<S extends BaseSpan>

All Known Subinterfaces:

ActiveSpan, Span

public interface BaseSpan<S extends BaseSpan>

BaseSpan represents the OpenTracing specification's span contract with the exception of methods to finish said span. For those, either use Span.finish() or ActiveSpan.deactivate() depending on the programming model.

See Also:

Span, ActiveSpan, Tracer.SpanBuilder.startManual(), Tracer.SpanBuilder.startActive()

Method Summary

Modifier and Type	Method and Description
SpanContext	context() Retrieve the associated SpanContext.
String	getBaggageItem(String key)
S	log(long timestampMicroseconds, Map<String,?> fields) Like log(Map<String, Object>), but with an explicit timestamp.
S	log(long timestampMicroseconds, String event) Record an event at a specific timestamp.
S	log(long timestampMicroseconds, String eventName, Object payload) Deprecated. use log(Map) like this span.log(timestampMicroseconds, Map.of("event", "timeout")) or span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))
S	log(Map<String,?> fields) Log key:value pairs to the Span with the current walltime timestamp.
S	log(String event) Record an event at the current walltime timestamp.
S	log(String eventName, Object payload) Deprecated. use log(Map) like this span.log(Map.of("event", "timeout")) or span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))
S	setBaggageItem(String key, String value) Sets a baggage item in the Span (and its SpanContext) as a key/value pair.
S	setOperationName(String operationName) Sets the string name for the logical operation this span represents.
S	setTag(String key, boolean value) Same as setTag(String, String), but for boolean values.
S	setTag(String key, Number value) Same as setTag(String, String), but for numeric values.
S	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

S setTag(String key,
         String value)

Set a key:value tag on the Span.

setTag

S setTag(String key,
         boolean value)

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

setTag

S setTag(String key,
         Number value)

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

log

S 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

S 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

S 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

S 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

S 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

S setOperationName(String operationName)

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

Returns:

this Span instance, for chaining

log

@Deprecated
S log(String eventName,
                  Object payload)

Deprecated. use log(Map) like this span.log(Map.of("event", "timeout")) or span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))

log

@Deprecated
S log(long timestampMicroseconds,
                  String eventName,
                  Object payload)

Deprecated. use log(Map) like this span.log(timestampMicroseconds, Map.of("event", "timeout")) or span.log(timestampMicroseconds, Map.of("event", "exception", "payload", stackTrace))