Trait OpenTelemetrySpanExt 

pub trait OpenTelemetrySpanExt {
    // Required methods
    fn set_parent(&self, cx: Context) -> Result<(), SetParentError>;
    fn add_link(&self, cx: SpanContext);
    fn add_link_with_attributes(
        &self,
        cx: SpanContext,
        attributes: Vec<KeyValue>,
    );
    fn context(&self) -> Context;
    fn set_attribute(&self, key: impl Into<Key>, value: impl Into<Value>);
    fn set_status(&self, status: Status);
    fn add_event(
        &self,
        name: impl Into<Cow<'static, str>>,
        attributes: Vec<KeyValue>,
    );
    fn add_event_with_timestamp(
        &self,
        name: impl Into<Cow<'static, str>>,
        timestamp: SystemTime,
        attributes: Vec<KeyValue>,
    );
}

Utility functions to allow tracing Spans to accept and return OpenTelemetry Contexts.

Required Methods

fn set_parent(&self, cx: Context) -> Result<(), SetParentError>

Associates self with a given OpenTelemetry trace, using the provided parent Context.

This method exists primarily to make it possible to inject a distributed incoming context, e.g. span IDs, etc.

A span’s parent should only be set once, for the purpose described above. Additionally, once a span has been fully built - and the SpanBuilder has been consumed - the parent cannot be mutated.

This method provides error handling for cases where the span context cannot be set, such as when the OpenTelemetry layer is not present or when the span has already been started.

Examples

use opentelemetry::{propagation::TextMapPropagator, trace::TraceContextExt};
use opentelemetry_sdk::propagation::TraceContextPropagator;
use tracing_opentelemetry::OpenTelemetrySpanExt;
use std::collections::HashMap;
use tracing::Span;

// Example carrier, could be a framework header map that impls otel's `Extractor`.
let mut carrier = HashMap::new();

// Propagator can be swapped with b3 propagator, jaeger propagator, etc.
let propagator = TraceContextPropagator::new();

// Extract otel parent context via the chosen propagator
let parent_context = propagator.extract(&carrier);

// Generate a tracing span as usual
let app_root = tracing::span!(tracing::Level::INFO, "app_start");

// Assign parent trace from external context
let _ = app_root.set_parent(parent_context.clone());

// Or if the current span has been created elsewhere:
let _ = Span::current().set_parent(parent_context);

fn add_link(&self, cx: SpanContext)

Associates self with a given OpenTelemetry trace, using the provided followed span SpanContext.

Examples

use opentelemetry::{propagation::TextMapPropagator, trace::TraceContextExt};
use opentelemetry_sdk::propagation::TraceContextPropagator;
use tracing_opentelemetry::OpenTelemetrySpanExt;
use std::collections::HashMap;
use tracing::Span;

// Example carrier, could be a framework header map that impls otel's `Extractor`.
let mut carrier = HashMap::new();

// Propagator can be swapped with b3 propagator, jaeger propagator, etc.
let propagator = TraceContextPropagator::new();

// Extract otel context of linked span via the chosen propagator
let linked_span_otel_context = propagator.extract(&carrier);

// Extract the linked span context from the otel context
let linked_span_context = linked_span_otel_context.span().span_context().clone();

// Generate a tracing span as usual
let app_root = tracing::span!(tracing::Level::INFO, "app_start");

// Assign linked trace from external context
app_root.add_link(linked_span_context);

// Or if the current span has been created elsewhere:
let linked_span_context = linked_span_otel_context.span().span_context().clone();
Span::current().add_link(linked_span_context);

fn add_link_with_attributes(&self, cx: SpanContext, attributes: Vec<KeyValue>)

Associates self with a given OpenTelemetry trace, using the provided followed span SpanContext and attributes.

fn context(&self) -> Context

Extracts an OpenTelemetry Context from self.

Examples

use opentelemetry::Context;
use tracing_opentelemetry::OpenTelemetrySpanExt;
use tracing::Span;

fn make_request(cx: Context) {
    // perform external request after injecting context
    // e.g. if the request's headers impl `opentelemetry::propagation::Injector`
    // then `propagator.inject_context(cx, request.headers_mut())`
}

// Generate a tracing span as usual
let app_root = tracing::span!(tracing::Level::INFO, "app_start");

// To include tracing context in client requests from _this_ app,
// extract the current OpenTelemetry context.
make_request(app_root.context());

// Or if the current span has been created elsewhere:
make_request(Span::current().context())

fn set_attribute(&self, key: impl Into<Key>, value: impl Into<Value>)

Sets an OpenTelemetry attribute directly for this span, bypassing tracing. If fields set here conflict with tracing fields, the tracing fields will supersede fields set with set_attribute. This allows for more than 32 fields.

Examples

use opentelemetry::Context;
use tracing_opentelemetry::OpenTelemetrySpanExt;
use tracing::Span;

// Generate a tracing span as usual
let app_root = tracing::span!(tracing::Level::INFO, "app_start");

// Set the `http.request.header.x_forwarded_for` attribute to `example`.
app_root.set_attribute("http.request.header.x_forwarded_for", "example");

fn set_status(&self, status: Status)

Sets an OpenTelemetry status for this span. This is useful for setting the status of a span that was created by a library that does not declare the otel.status_code field of the span in advance.

Examples

use opentelemetry::trace::Status;
use tracing_opentelemetry::OpenTelemetrySpanExt;
use tracing::Span;

/// // Generate a tracing span as usual
let app_root = tracing::span!(tracing::Level::INFO, "app_start");

// Set the Status of the span to `Status::Ok`.
app_root.set_status(Status::Ok);

fn add_event( &self, name: impl Into<Cow<'static, str>>, attributes: Vec<KeyValue>, )

Adds an OpenTelemetry event directly to this span, bypassing tracing::event!. This allows for adding events with dynamic attribute keys, similar to set_attribute for span attributes. Events are added with the current timestamp.

Examples

use opentelemetry::{KeyValue};
use tracing_opentelemetry::OpenTelemetrySpanExt;
use tracing::Span;

let app_root = tracing::span!(tracing::Level::INFO, "processing_request");

let dynamic_attrs = vec![
    KeyValue::new("job_id", "job-123"),
    KeyValue::new("user.id", "user-xyz"),
];

// Add event using the extension method
app_root.add_event("job_started".to_string(), dynamic_attrs);

// ... perform work ...

app_root.add_event("job_completed", vec![KeyValue::new("status", "success")]);

fn add_event_with_timestamp( &self, name: impl Into<Cow<'static, str>>, timestamp: SystemTime, attributes: Vec<KeyValue>, )

Adds an OpenTelemetry event with a specific timestamp directly to this span. Similar to add_event, but allows overriding the event timestamp.

Examples

use opentelemetry::{KeyValue};
use tracing_opentelemetry::OpenTelemetrySpanExt;
use tracing::Span;
use std::time::{Duration, SystemTime};
use std::borrow::Cow;

let app_root = tracing::span!(tracing::Level::INFO, "historical_event_processing");

let event_time = SystemTime::now() - Duration::from_secs(60);
let event_attrs = vec![KeyValue::new("record_id", "rec-456")];
let event_name: Cow<'static, str> = "event_from_past".into();

app_root.add_event_with_timestamp(event_name, event_time, event_attrs);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl OpenTelemetrySpanExt for Span

fn set_parent(&self, cx: Context) -> Result<(), SetParentError>

fn add_link(&self, cx: SpanContext)

fn add_link_with_attributes(&self, cx: SpanContext, attributes: Vec<KeyValue>)

fn context(&self) -> Context

fn set_attribute(&self, key: impl Into<Key>, value: impl Into<Value>)

fn set_status(&self, status: Status)

fn add_event( &self, name: impl Into<Cow<'static, str>>, attributes: Vec<KeyValue>, )

fn add_event_with_timestamp( &self, name: impl Into<Cow<'static, str>>, timestamp: SystemTime, attributes: Vec<KeyValue>, )

Implementors