@ThreadSafe
public interface Span
SpanContext
.
Spans are created by the Span.Builder.startSpan()
method.
Span
must be ended by calling end()
.
Modifier and Type | Interface and Description |
---|---|
static interface |
Span.Builder
Span.Builder is used to construct Span instances which define arbitrary scopes of
code that are sampled for distributed tracing as a single atomic unit. |
static class |
Span.Kind
Type of span.
|
Modifier and Type | Method and Description |
---|---|
void |
addEvent(java.lang.String name)
Adds an event to the
Span . |
void |
addEvent(java.lang.String name,
Attributes attributes)
Adds an event to the
Span with the given Attributes . |
void |
addEvent(java.lang.String name,
Attributes attributes,
long timestamp)
|
void |
addEvent(java.lang.String name,
long timestamp)
Adds an event to the
Span with the given timestamp , as nanos since epoch. |
void |
end()
Marks the end of
Span execution. |
void |
end(EndSpanOptions endOptions)
Marks the end of
Span execution with the specified EndSpanOptions . |
SpanContext |
getContext()
Returns the
SpanContext associated with this Span . |
boolean |
isRecording()
Returns
true if this Span records tracing events (e.g. |
void |
recordException(java.lang.Throwable exception)
Records information about the
Throwable to the Span . |
void |
recordException(java.lang.Throwable exception,
Attributes additionalAttributes)
Records information about the
Throwable to the Span . |
default void |
setAttribute(AttributeKey<java.lang.Long> key,
int value)
Sets an attribute to the
Span . |
<T> void |
setAttribute(AttributeKey<T> key,
T value)
Sets an attribute to the
Span . |
void |
setAttribute(java.lang.String key,
boolean value)
Sets an attribute to the
Span . |
void |
setAttribute(java.lang.String key,
double value)
Sets an attribute to the
Span . |
void |
setAttribute(java.lang.String key,
long value)
Sets an attribute to the
Span . |
void |
setAttribute(java.lang.String key,
java.lang.String value)
Sets an attribute to the
Span . |
void |
setStatus(StatusCanonicalCode canonicalCode)
Sets the status to the
Span . |
void |
setStatus(StatusCanonicalCode canonicalCode,
java.lang.String description)
Sets the status to the
Span . |
void |
updateName(java.lang.String name)
Updates the
Span name. |
void setAttribute(java.lang.String key, @Nonnull java.lang.String value)
Span
. If the Span
previously contained a mapping for
the key, the old value is replaced by the specified value.
If a null or empty String value
is passed in, the behavior is undefined, and hence
strongly discouraged.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.void setAttribute(java.lang.String key, long value)
Span
. If the Span
previously contained a mapping for
the key, the old value is replaced by the specified value.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.void setAttribute(java.lang.String key, double value)
Span
. If the Span
previously contained a mapping for
the key, the old value is replaced by the specified value.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.void setAttribute(java.lang.String key, boolean value)
Span
. If the Span
previously contained a mapping for
the key, the old value is replaced by the specified value.
Note: It is strongly recommended to use setAttribute(AttributeKey, Object)
, and
pre-allocate your keys, if possible.
key
- the key for this attribute.value
- the value for this attribute.<T> void setAttribute(AttributeKey<T> key, @Nonnull T value)
Span
. If the Span
previously contained a mapping for
the key, the old value is replaced by the specified value.
Note: the behavior of null values is undefined, and hence strongly discouraged.
key
- the key for this attribute.value
- the value for this attribute.default void setAttribute(AttributeKey<java.lang.Long> key, int value)
Span
. If the Span
previously contained a mapping for
the key, the old value is replaced by the specified value.key
- the key for this attribute.value
- the value for this attribute.void addEvent(java.lang.String name)
Span
. The timestamp of the event will be the current time.name
- the name of the event.void addEvent(java.lang.String name, long timestamp)
Span
with the given timestamp
, as nanos since epoch. Note,
this timestamp
is not the same as System.nanoTime()
but may be computed using
it, for example, by taking a difference of readings from System.nanoTime()
and adding
to the span start time.
When possible, it is preferred to use addEvent(String)
at the time the event
occurred.
name
- the name of the event.timestamp
- the explicit event timestamp in nanos since epoch.void addEvent(java.lang.String name, Attributes attributes)
Span
with the given Attributes
. The timestamp of the event
will be the current time.name
- the name of the event.attributes
- the attributes that will be added; these are associated with this event, not
the Span
as for setAttribute()
.void addEvent(java.lang.String name, Attributes attributes, long timestamp)
Span
with the given Attributes
and timestamp
.
Note, this timestamp
is not the same as System.nanoTime()
but may be computed
using it, for example, by taking a difference of readings from System.nanoTime()
and
adding to the span start time.
When possible, it is preferred to use addEvent(String)
at the time the event
occurred.
name
- the name of the event.attributes
- the attributes that will be added; these are associated with this event, not
the Span
as for setAttribute()
.timestamp
- the explicit event timestamp in nanos since epoch.void setStatus(StatusCanonicalCode canonicalCode)
Span
.
If used, this will override the default Span
status. Default status code is StatusCanonicalCode.UNSET
.
Only the value of the last call will be recorded, and implementations are free to ignore previous calls.
canonicalCode
- the StatusCanonicalCode
to set.void setStatus(StatusCanonicalCode canonicalCode, java.lang.String description)
Span
.
If used, this will override the default Span
status. Default status code is StatusCanonicalCode.UNSET
.
Only the value of the last call will be recorded, and implementations are free to ignore previous calls.
canonicalCode
- the StatusCanonicalCode
to set.description
- the description of the Status
.void recordException(java.lang.Throwable exception)
Throwable
to the Span
.
Note that SemanticAttributes.EXCEPTION_ESCAPED
cannot be determined by this function. You should record this attribute manually using recordException(Throwable, Attributes)
if you know that an exception is escaping.
exception
- the Throwable
to record.void recordException(java.lang.Throwable exception, Attributes additionalAttributes)
Throwable
to the Span
.exception
- the Throwable
to record.additionalAttributes
- the additional Attributes
to record.void updateName(java.lang.String name)
Span
name.
If used, this will override the name provided via Span.Builder
.
Upon this update, any sampling behavior based on Span
name will depend on the
implementation.
name
- the Span
name.void end()
Span
execution.
Only the timing of the first end call for a given Span
will be recorded, and
implementations are free to ignore all further calls.
void end(EndSpanOptions endOptions)
Span
execution with the specified EndSpanOptions
.
Only the timing of the first end call for a given Span
will be recorded, and
implementations are free to ignore all further calls.
Use this method for specifying explicit end options, such as end Timestamp
. When no
explicit values are required, use end()
.
endOptions
- the explicit EndSpanOptions
for this Span
.SpanContext getContext()
SpanContext
associated with this Span
.SpanContext
associated with this Span
.boolean isRecording()
true
if this Span
records tracing events (e.g. addEvent(String)
, setAttribute(String, long)
).true
if this Span
records tracing events.