Struct opentelemetry::api::context::Context

pub struct Context { /* fields omitted */ }

An execution-scoped collection of values.

Implementations

impl Context

pub fn new() -> Self

Creates an empty Context.

The context is initially created with a capacity of 0, so it will not allocate. Use with_value to create a new context that has entries.

pub fn current() -> Self

Returns an immutable snapshot of the current thread's context.

Examples

use opentelemetry::api::Context;

#[derive(Debug, PartialEq)]
struct ValueA(&'static str);

fn do_work() {
    assert_eq!(Context::current().get(), Some(&ValueA("a")));
}

let _guard = Context::new().with_value(ValueA("a")).attach();
do_work()

pub fn current_with_value<T: 'static>(value: T) -> Self

Returns a clone of the current thread's context with the given value.

This is a more efficient form of Context::current().with_value(value) as it avoids the intermediate context clone.

Examples

use opentelemetry::api::Context;

// Given some value types defined in your application
#[derive(Debug, PartialEq)]
struct ValueA(&'static str);
#[derive(Debug, PartialEq)]
struct ValueB(u64);

// You can create and attach context with the first value set to "a"
let _guard = Context::new().with_value(ValueA("a")).attach();

// And create another context based on the fist with a new value
let all_current_and_b = Context::current_with_value(ValueB(42));

// The second context now contains all the current values and the addition
assert_eq!(all_current_and_b.get::<ValueA>(), Some(&ValueA("a")));
assert_eq!(all_current_and_b.get::<ValueB>(), Some(&ValueB(42)));

pub fn get<T: 'static>(&self) -> Option<&T>

Returns a reference to the entry for the corresponding value type.

Examples

use opentelemetry::api::Context;

// Given some value types defined in your application
#[derive(Debug, PartialEq)]
struct ValueA(&'static str);
#[derive(Debug, PartialEq)]
struct MyUser();

let cx = Context::new().with_value(ValueA("a"));

// Values can be queried by type
assert_eq!(cx.get::<ValueA>(), Some(&ValueA("a")));

// And return none if not yet set
assert_eq!(cx.get::<MyUser>(), None);

pub fn with_value<T: 'static>(&self, value: T) -> Self

Returns a copy of the context with the new value included.

Examples

use opentelemetry::api::Context;

// Given some value types defined in your application
#[derive(Debug, PartialEq)]
struct ValueA(&'static str);
#[derive(Debug, PartialEq)]
struct ValueB(u64);

// You can create a context with the first value set to "a"
let cx_with_a = Context::new().with_value(ValueA("a"));

// And create another context based on the fist with a new value
let cx_with_a_and_b = cx_with_a.with_value(ValueB(42));

// The first context is still available and unmodified
assert_eq!(cx_with_a.get::<ValueA>(), Some(&ValueA("a")));
assert_eq!(cx_with_a.get::<ValueB>(), None);

// The second context now contains both values
assert_eq!(cx_with_a_and_b.get::<ValueA>(), Some(&ValueA("a")));
assert_eq!(cx_with_a_and_b.get::<ValueB>(), Some(&ValueB(42)));

pub fn attach(self) -> ContextGuard

Replaces the current context on this thread with this context.

Dropping the returned ContextGuard will reset the current context to the previous value.

Examples

use opentelemetry::api::Context;

#[derive(Debug, PartialEq)]
struct ValueA(&'static str);

let my_cx = Context::new().with_value(ValueA("a"));

// Set the current thread context
let cx_guard = my_cx.attach();
assert_eq!(Context::current().get::<ValueA>(), Some(&ValueA("a")));

// Drop the guard to restore the previous context
drop(cx_guard);
assert_eq!(Context::current().get::<ValueA>(), None);

Guards do not need to be explicitly dropped:

use opentelemetry::api::Context;

#[derive(Debug, PartialEq)]
struct ValueA(&'static str);

fn my_function() -> String {
    // attach a context the duration of this function.
    let my_cx = Context::new().with_value(ValueA("a"));
    // NOTE: a variable name after the underscore is **required** or rust
    // will drop the guard, restoring the previous context _immediately_.
    let _guard = my_cx.attach();

    // anything happening in functions we call can still access my_cx...
    my_other_function();

    // returning from the function drops the guard, exiting the span.
    return "Hello world".to_owned();
}

fn my_other_function() {
    // ...
}

Sub-scopes may be created to limit the duration for which the span is entered:

use opentelemetry::api::Context;

#[derive(Debug, PartialEq)]
struct ValueA(&'static str);

let my_cx = Context::new().with_value(ValueA("a"));

{
    let _guard = my_cx.attach();

    // the current context can access variables in
    assert_eq!(Context::current().get::<ValueA>(), Some(&ValueA("a")));

    // exiting the scope drops the guard, detaching the context.
}

// this is back in the default empty context
assert_eq!(Context::current().get::<ValueA>(), None);

Trait Implementations

impl Clone for Context

fn clone(&self) -> Context

Returns a copy of the value.

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

Performs copy-assignment from source.

impl CorrelationContextExt for Context

fn current_with_correlations<T: IntoIterator<Item = KeyValue>>(kvs: T) -> Self

Returns a clone of the current context with the included name / value pairs.

fn with_correlations<T: IntoIterator<Item = KeyValue>>(&self, kvs: T) -> Self

Returns a clone of the given context with the included name / value pairs.

fn with_cleared_correlations(&self) -> Self

Returns a clone of the given context with the included name / value pairs.

fn correlation_context(&self) -> &CorrelationContext

Returns a reference to this context's correlation context, or the default empty correlation context if none has been set.

impl Debug for Context

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

Formats the value using the given formatter.

impl Default for Context

fn default() -> Context

Returns the "default value" for a type.

impl TraceContextExt for Context

fn current_with_span<T: Span>(span: T) -> Self

Returns a clone of the current context with the included span.

fn with_span<T: Span>(&self, span: T) -> Self

Returns a clone of this context with the included span.

fn span(&self) -> &dyn Span

Returns a reference to this context's span, or the default no-op span if none has been set.

fn with_remote_span_context(&self, span_context: SpanContext) -> Self

Returns a copy of this context with the span context included.

fn remote_span_context(&self) -> Option<&SpanContext>

Returns a reference to the remote span context data stored in this context, or none if no remote span context has been set.