Struct Span

pub struct Span { /* private fields */ }

Expand description

A distributed tracing span representing a unit of work.

Spans are the fundamental building blocks of distributed tracing. They represent a unit of work within a trace and can be nested to show relationships between different operations.

§Examples

use veecle_telemetry::{KeyValue, Span, Value};

// Create a span with attributes
let span = Span::new("database_query", &[
    KeyValue::new("table", Value::String("users".into())),
    KeyValue::new("operation", Value::String("SELECT".into())),
]);

// Enter the span to make it active
let _guard = span.enter();

// Add events to the span
span.add_event("query_executed", &[]);

§Conditional Compilation

When the enable feature is disabled, spans compile to no-ops with zero runtime overhead.

Implementations§

§

impl Span

pub fn noop() -> Span

Creates a no-op span that performs no tracing operations.

This is useful for creating spans that may be conditionally enabled or when telemetry is completely disabled.

pub fn new(name: &'static str, attributes: &[KeyValue<'static>]) -> Span

Creates a new span as a child of the current span.

If there is no current span, this returns a no-op span. Uses Span::root to create a root span with a specific context.

§Arguments

name - The name of the span
attributes - Key-value attributes to attach to the span

§Examples

use veecle_telemetry::{KeyValue, Span, Value};

let span = Span::new("operation", &[KeyValue::new("user_id", Value::I64(123))]);

pub fn root( name: &'static str, span_context: SpanContext, attributes: &[KeyValue<'static>], ) -> Span

Creates a new root span with the given context.

Unlike new(), this method does not use the current span from CURRENT_SPAN and creates a true root span with no parent using the provided SpanContext directly.

§Examples

use veecle_telemetry::{Span, SpanContext};

let context = SpanContext::generate();
let span = Span::root("root_span", context, &[]);

pub fn enter(&self) -> SpanGuardRef<'_>

Enters this span, making it the current active span.

This method returns a guard that will automatically exit the span when dropped. The guard borrows the span, so the span must remain alive while the guard exists.

§Examples

use veecle_telemetry::Span;

let span = Span::new("operation", &[]);
let _guard = span.enter();
// span is now active
// span is automatically exited when _guard is dropped

pub fn entered(self) -> SpanGuard

Enters this span by taking ownership of it.

This method consumes the span and returns a guard that owns the span. The span will be automatically exited and closed when the guard is dropped.

§Examples

use veecle_telemetry::Span;

let span = Span::new("operation", &[]);
let _guard = span.entered();
// span is now active and owned by the guard
// span is automatically exited and closed when _guard is dropped

pub fn add_event(&self, name: &'static str, attributes: &[KeyValue<'static>])

Adds an event to this span.

Events represent point-in-time occurrences within a span’s lifetime. They can include additional attributes for context.

§Arguments

name - The name of the event
attributes - Key-value attributes providing additional context

§Examples

use veecle_telemetry::{KeyValue, Span, Value};

let span = Span::new("database_query", &[]);
span.add_event("query_started", &[]);
span.add_event("query_completed", &[KeyValue::new("rows_returned", Value::I64(42))]);

pub fn add_link(&self, link: SpanContext)

Creates a link from this span to another span.

Links connect spans across different traces, allowing you to represent relationships between spans that are not parent-child relationships.

§Examples

use veecle_telemetry::{Span, SpanContext, SpanId, TraceId};

let span = Span::new("my_span", &[]);
let external_context = SpanContext::new(TraceId(0x123), SpanId(0x456));
span.add_link(external_context);

pub fn set_attribute(&self, attribute: KeyValue<'static>)

Adds an attribute to this span.

Attributes provide additional context about the work being performed in the span. They can be set at any time during the span’s lifetime.

§Arguments

attribute - The key-value attribute to set

§Examples

use veecle_telemetry::{KeyValue, Span, Value};

let span = Span::new("user_operation", &[]);
span.set_attribute(KeyValue::new("user_id", Value::I64(123)));
span.set_attribute(KeyValue::new("operation_type", Value::String("update".into())));