Trait opentelemetry::trace::Span

pub trait Span: Debug + 'static + Send + Sync {
    fn add_event_with_timestamp(
        &self, 
        name: String, 
        timestamp: SystemTime, 
        attributes: Vec<KeyValue>
    );
    fn span_context(&self) -> &SpanContext;
    fn is_recording(&self) -> bool;
    fn set_attribute(&self, attribute: KeyValue);
    fn set_status(&self, code: StatusCode, message: String);
    fn update_name(&self, new_name: String);
    fn end_with_timestamp(&self, timestamp: SystemTime);

    fn add_event(&self, name: String, attributes: Vec<KeyValue>) { ... }
    fn record_exception(&self, err: &dyn Error) { ... }
    fn record_exception_with_stacktrace(
        &self, 
        err: &dyn Error, 
        stacktrace: String
    ) { ... }
    fn end(&self) { ... }
}

This is supported on crate feature trace only.

Interface for a single operation within a trace.

Required methods

fn add_event_with_timestamp(
    &self,
    name: String,
    timestamp: SystemTime,
    attributes: Vec<KeyValue>
)

An API to record events at a specific time in the context of a given Span.

Events SHOULD preserve the order in which they’re set. This will typically match the ordering of the events’ timestamps.

Note that the OpenTelemetry project documents certain “standard event names and keys” which have prescribed semantic meanings.

fn span_context(&self) -> &SpanContext

Returns the SpanContext for the given Span. The returned value may be used even after the Span is finished. The returned value MUST be the same for the entire Span` lifetime.

fn is_recording(&self) -> bool

Returns true if this Span is recording information like events with the add_event operation, attributes using set_attributes, status with set_status, etc.

This flag SHOULD be used to avoid expensive computations of a Span attributes or events in case when a Span is definitely not recorded. Note that any child span’s recording is determined independently from the value of this flag (typically based on the sampled flag of a TraceFlag on SpanContext).

This flag may be true despite the entire trace being sampled out. This allows to record and process information about the individual Span without sending it to the backend. An example of this scenario may be recording and processing of all incoming requests for the processing and building of SLA/SLO latency charts while sending only a subset - sampled spans - to the backend. See also the sampling section of SDK design.

Users of the API should only access the is_recording property when instrumenting code and never access SampledFlag unless used in context propagators.

fn set_attribute(&self, attribute: KeyValue)

An API to set a single Attribute where the attribute properties are passed as arguments. To avoid extra allocations some implementations may offer a separate API for each of the possible value types.

An Attribute is defined as a KeyValue pair.

Attributes SHOULD preserve the order in which they’re set. Setting an attribute with the same key as an existing attribute SHOULD overwrite the existing attribute’s value.

Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings.

fn set_status(&self, code: StatusCode, message: String)

Sets the status of the Span. If used, this will override the default Span status, which is Unset. message MUST be ignored when the status is OK or Unset

Only the value of the last call will be recorded, and implementations are free to ignore previous calls.

fn update_name(&self, new_name: String)

Updates the Span’s name. After this update, any sampling behavior based on the name will depend on the implementation.

It is highly discouraged to update the name of a Span after its creation. Span name is often used to group, filter and identify the logical groups of spans. Often, filtering logic will be implemented before the Span creation for performance reasons, and the name update may interfere with this logic.

The method name is called update_name to differentiate this method from the regular property. It emphasizes that this operation signifies a major change for a Span and may lead to re-calculation of sampling or filtering decisions made previously depending on the implementation.

fn end_with_timestamp(&self, timestamp: SystemTime)

Finishes the Span with given timestamp

For more details, refer to Span::end

Loading content...

Provided methods

fn add_event(&self, name: String, attributes: Vec<KeyValue>)

An API to record events in the context of a given Span.

Events have a time associated with the moment when they are added to the Span.

Events SHOULD preserve the order in which they’re set. This will typically match the ordering of the events’ timestamps.

Note that the OpenTelemetry project documents certain “standard event names and keys” which have prescribed semantic meanings.

fn record_exception(&self, err: &dyn Error)

Convenience method to record an exception/error as an Event

An exception SHOULD be recorded as an Event on the span during which it occurred. The name of the event MUST be “exception”.

The semantic conventions for Errors are described in “Semantic Conventions for Exceptions”

For now we will not set exception.stacktrace attribute since the Error::backtrace method is still in nightly. Users can provide a stacktrace by using the record_exception_with_stacktrace method.

Users can custom the exception message by overriding the fmt::Display trait’s fmt method for the error.

fn record_exception_with_stacktrace(&self, err: &dyn Error, stacktrace: String)

Convenience method to record a exception/error as an Event with custom stacktrace

See Span:record_exception method for more details.

fn end(&self)

Finishes the Span.

Implementations MUST ignore all subsequent calls to end (there might be exceptions when the tracer is streaming events and has no mutable state associated with the Span).

Calls to end a Span MUST not have any effects on child Spans as they may still be running and can be ended later.

This API MUST be non-blocking.

Loading content...

Implementors

impl Span for BoxedSpan

fn add_event_with_timestamp(
    &self,
    name: String,
    timestamp: SystemTime,
    attributes: Vec<KeyValue>
)

This is supported on crate feature trace only.

Records events at a specific time in the context of a given Span.

Note that the OpenTelemetry project documents certain “standard event names and keys” which have prescribed semantic meanings.

fn span_context(&self) -> &SpanContext

This is supported on crate feature trace only.

Returns the SpanContext for the given Span.

fn is_recording(&self) -> bool

This is supported on crate feature trace only.

Returns true if this Span is recording information like events with the add_event operation, attributes using set_attributes, status with set_status, etc.

fn set_attribute(&self, attribute: KeyValue)

This is supported on crate feature trace only.

Sets a single Attribute where the attribute properties are passed as arguments.

Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings.

fn set_status(&self, code: StatusCode, message: String)

This is supported on crate feature trace only.

Sets the status of the Span. If used, this will override the default Span status, which is Unset.

fn update_name(&self, new_name: String)

This is supported on crate feature trace only.

Updates the Span’s name.

fn end_with_timestamp(&self, timestamp: SystemTime)

This is supported on crate feature trace only.

Finishes the span with given timestamp.

impl Span for Span

fn add_event_with_timestamp(
    &self,
    name: String,
    timestamp: SystemTime,
    attributes: Vec<KeyValue>
)

Records events at a specific time in the context of a given Span.

Note that the OpenTelemetry project documents certain “standard event names and keys” which have prescribed semantic meanings.

fn span_context(&self) -> &SpanContext

Returns the SpanContext for the given Span.

fn is_recording(&self) -> bool

Returns true if this Span is recording information like events with the add_event operation, attributes using set_attributes, status with set_status, etc. Always returns false after span end.

fn set_attribute(&self, attribute: KeyValue)

Sets a single Attribute where the attribute properties are passed as arguments.

Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings.

fn set_status(&self, code: StatusCode, message: String)

Sets the status of the Span. If used, this will override the default Span status, which is Unset. message MUST be ignored when the status is OK or Unset

fn update_name(&self, new_name: String)

Updates the Span’s name.

fn end_with_timestamp(&self, timestamp: SystemTime)

Finishes the span with given timestamp.

impl Span for TestSpan

fn add_event_with_timestamp(
    &self,
    _name: String,
    _timestamp: SystemTime,
    _attributes: Vec<KeyValue>
)

This is supported on crate feature trace only.

fn span_context(&self) -> &SpanContext

This is supported on crate feature trace only.

fn is_recording(&self) -> bool

This is supported on crate feature trace only.

fn set_attribute(&self, _attribute: KeyValue)

This is supported on crate feature trace only.

fn set_status(&self, _code: StatusCode, _message: String)

This is supported on crate feature trace only.

fn update_name(&self, _new_name: String)

This is supported on crate feature trace only.

fn end_with_timestamp(&self, _timestamp: SystemTime)

This is supported on crate feature trace only.

impl Span for NoopSpan

fn add_event(&self, _name: String, _attributes: Vec<KeyValue>)

Ignores all events

fn add_event_with_timestamp(
    &self,
    _name: String,
    _timestamp: SystemTime,
    _attributes: Vec<KeyValue>
)

Ignores all events with timestamps

fn span_context(&self) -> &SpanContext

Returns an invalid SpanContext.

fn is_recording(&self) -> bool

Returns false, signifying that this span is never recording.

fn set_attribute(&self, _attribute: KeyValue)

Ignores all attributes

fn set_status(&self, _code: StatusCode, _message: String)

Ignores status

fn update_name(&self, _new_name: String)

Ignores name updates

fn end_with_timestamp(&self, _timestamp: SystemTime)

Ignores Span endings

Loading content...