APISpan class
Span represents a single operation within a trace. The API prefix indicates that it's part of the API and not the SDK and generally should not be used since an API without an SDK is a noop. Use the TracerProvider from the SDK instead. Spans can be nested to form a trace tree. Each trace contains a root span, which typically describes the end-to-end latency, and zero or more sub-spans for its sub-operations. Any span that is created MUST also be ended. This is the responsibility of the user. API implementations MAY leak memory or other resources (including, for example, CPU time for periodic work that iterates all spans) if the user forgot to end the span.
Properties
- attributes ↔ Attributes
-
Only exposed for testing. Spans are not meant to be used to propagate
information within a process. To prevent misuse, implementations
SHOULD NOT provide access to a Span's attributes besides its SpanContext
getter/setter pair
- endTime → DateTime?
-
The end time of this APISpan.
no setter
- hashCode → int
-
The hash code for this object.
no setteroverride
- instrumentationScope → InstrumentationScope
-
Returns the instrumentation scope for this span
no setter
- isEnded → bool
-
Returns whether this span has been ended
no setter
- isRecording → bool
-
Returns true if this Span is recording information like events, attributes, status, etc.
no setter
- isValid → bool
-
Returns whether this span context is valid
A span context is valid when it has a non-zero traceId and a non-zero spanId.
no setter
- kind → SpanKind
-
Returns the SpanKind of this Span.
no setter
- name → String
-
The name of this APISpan.
no setter
- parentSpan → APISpan?
-
Returns the parent span, if any.
Root spans have no parent.
no setter
- parentSpanContext → SpanContext?
-
Returns the parent span context, if any.
Root spans have no parent span context.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- spanContext → SpanContext
-
Returns the SpanContext associated with this Span, if any.
Root spans have no SpanContext.
no setter
-
spanEvents
→ List<
SpanEvent> ? -
Returns an unmodifiable List of SpanEvents associated with this Span.
no setter
- spanId → SpanId
-
Returns the id of this Span, if any.
Root spans have no SpanId.
no setter
-
spanLinks
→ List<
SpanLink> ? -
Returns the SpanLinks associated with this Span.
no setter
- startTime → DateTime
-
The start time of this APISpan.
no setter
- status → SpanStatusCode
-
The status of this APISpan.
no setter
- statusDescription → String?
-
The status of this APISpan.
no setter
Methods
-
addAttributes(
Attributes attributes) → void - Adds multiple attributes to the span at once by merging with existing attributes. This is more efficient than calling individual attribute setters when you need to add multiple attributes.
-
addEvent(
SpanEvent spanEvent) → void - Adds an event to the Span. Ignored if isEnded Note that the OpenTelemetry project documents certain "standard event names and keys" which have prescribed semantic meanings. See https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md
-
addEventNow(
String name, [Attributes? attributes]) → void - Adds an event to the Span. Ignored if isEnded
-
addEvents(
Map< String, Attributes?> spanEvents) → void - Adds an events to the Span from a map of names and attributes. Ignored if isEnded
-
addLink(
SpanContext spanContext, [Attributes? attributes]) → void -
Adds a link to this Span.
Ignored if the span is ended.
spanContextthe span context for the span -
addSpanLink(
SpanLink spanLink) → void - Adds a link to this Span. Ignored if the span is ended.
-
end(
{DateTime? endTime, SpanStatusCode? spanStatus}) → void - Marks the end of the Span execution. By default the end time is set to the calling time and the span status is SpanStatusCode.Ok
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
recordException(
Object exception, {StackTrace? stackTrace, Attributes? attributes, bool? escaped}) → void - Record an exception for the span. Does NOT set the status.
-
setBoolAttribute(
String name, bool value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setBoolListAttribute(
String name, List< bool> value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setDateTimeAsStringAttribute(
String name, DateTime value) → void - Sets String attribute from a DateTime, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setDoubleAttribute(
String name, double value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setDoubleListAttribute(
String name, List< double> value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setIntAttribute(
String name, int value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setIntListAttribute(
String name, List< int> value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setStatus(
SpanStatusCode statusCode, [String? description]) → void -
Sets the status of the Span. Ignored if isEnded
Setting
StatuswithStatusCode=Okwill override any prior or future attempts to set spanStatuswithStatusCode=ErrororStatusCode=UnsetdescriptionAn optional description of the status. An emptyDescriptionis equivalent with a not present one. Attempts to set value Unset is ignored.descriptionWhenstatusCodeis error, description should include the error's toString() if an exception is caught available. -
setStringAttribute<
T> (String name, String value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
setStringListAttribute<
T> (String name, List< String> value) → void - Sets an attribute, replacing any existing attribute with the same name/key Adding attributes at span creation is preferred to calling set attribute later, as samplers can only consider information already present during span creation. Ignored if isEnded
-
toString(
) → String -
A string representation of this object.
override
-
updateName(
String name) → void - Updates the Span name.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
override