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.

All methods of this class are safe for concurrent use by default: implementations must remain correct when methods are invoked from interleaved asynchronous tasks within an isolate. See Trace API, concurrency requirements.

Implementers

NonRecordingSpan

Properties

attributes ← Attributes: Sets the attributes, replacing all existing attributes since implementations SHOULD NOT provide access to a Span's attributes besides its SpanContext. 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
no getter
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: Read access to what this span recorded is deliberately not here. trace/api.md says implementations SHOULD NOT provide access to a Span's attributes besides its SpanContext. An SDK reads them through getReadableSpan, which is not exported from the package barrel. 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
spanId → SpanId: Returns the id of this Span, if any. Root spans have no SpanId.
no setter
startTime → DateTime: The start time 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.
addSpanLink(SpanLink spanLink) → void: Adds a link to this Span.
end({DateTime? endTime, SpanStatusCode? spanStatus}) → void: Marks the end of the Span execution.
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 Status with StatusCode=Ok will override any prior or future attempts to set span Status with StatusCode=Error or StatusCode=Unset description An optional description of the status. An empty Description is equivalent with a not present one. Attempts to set value Unset is ignored. description When statusCode is 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

APISpan class

Properties

Methods

Operators

dartastic_opentelemetry_api library