Struct opentracingrust::SpanContext

pub struct SpanContext { /* fields omitted */ }

Trecer-specific span and trace identifier and metadata.

An OpenTracing SpanContext is an abstraction that holds:

• Baggage items: key-value pairs that are propagated though the trace.
• Tracer specific details: such as the trace and span ids, flags, and other information that are needed by the concrete tracer (Zipkin, Jaeger, ...).

OpenTracingRust splits this abstraction into two:

• The SpanContext struct: holding all the common data.
• The ImplContext trait: holding implementation details.

The SpanContext holds information that is common to all TracerInterface implementors. This currently means baggage items only.

Baggage items are key/value pairs that are propagated through a trace. They are copied to derived spans every time a SpanContext is referenced by a Span. Baggage items are NOT propagated backwards to parent spans.

Examples

extern crate crossbeam_channel;
extern crate opentracingrust;

use crossbeam_channel::unbounded;

use opentracingrust::ImplContextBox;
use opentracingrust::Span;
use opentracingrust::SpanContext;
use opentracingrust::SpanReference;
use opentracingrust::SpanReferenceAware;
use opentracingrust::StartOptions;

#[derive(Clone)]
struct Context {
    // ... snip ...
}

impl SpanReferenceAware for Context {
    fn reference_span(&mut self, _: &SpanReference) {
        // ... snip ...
    }
}


fn main() {
    let mut context = SpanContext::new(ImplContextBox::new(Context {}));
    context.set_baggage_item(String::from("key1"), String::from("value1"));

    let (sender, _) = unbounded();
    let mut span = Span::new(
        "test",
        SpanContext::new(ImplContextBox::new(Context {})),
        StartOptions::default().child_of(context.clone()),
        sender
    );
    span.set_baggage_item("key2", "value2");

    // The parent context has one item.
    let items: Vec<(&str, &str)> = context.baggage_items()
        .map(|(k, v)| (&k[..], &v[..]))
        .collect();
    assert_eq!(items, [("key1", "value1")]);

    // The child context has two.
    let mut items: Vec<(&str, &str)> = span.context().baggage_items()
        .map(|(k, v)| (&k[..], &v[..]))
        .collect();
    items.sort();
    assert_eq!(items, [("key1", "value1"), ("key2", "value2")]);
}

Methods

impl SpanContext

pub fn new<Context: ImplContext + 'static>(inner: Context) -> SpanContext

Creates a new SpanContext.

The new SpanContext has no baggage items and holds the given ImplContext trait object.

impl SpanContext

pub fn impl_context<T: Any>(&self) -> Option<&T>

Attempt to access the SpanContext's tracer details.

This method is for use by TracerInterface developers to extract the tracer-specific span context for inject and referencing operations.

Since only one Tracer implementation should be used throughout the running process instances of SpanContext are expected to hold the correct concrete ImplContext.

It is acceptable for Tracers to panic when asked to operate on SpanContexts that do not hold the Tracer's ImplContext.

pub fn baggage_items(&self) -> Iter<String, String>

Iterates over baggage items.

The method returns an iterator over (key, value) tuples.

pub fn get_baggage_item(&self, key: &str) -> Option<&String>

Attempt to fetch a baggage item by key.

If there is no item with the given key this method returns None.

pub fn reference_span(&mut self, reference: &SpanReference)

Update this SpanContext to reference another span.

This method should not be called by users directly but is instead called by the Span referencing methods (child_of, follows).

This method will call the ImplContext::reference_span method.

pub fn set_baggage_item(&mut self, key: String, value: String)

Adds or updates the baggage items with the given key/value pair.

Baggage items are forwarded to Spans that reference this SpanContext and all the Spans that follows them.

Baggage items are NOT propagated backwards to Spans that reference this SpanContext.

Trait Implementations

impl Clone for SpanContext

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SpanContext

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.