Module opentelemetry::global

OpenTelemetry Global API

The global API provides applications access to their configured TracerProvider instance from anywhere in the codebase. This allows applications to be less coupled to the specific Open Telemetry SDK as well as not manually pass references to each part of the code that needs to create Spans. Additionally, 3rd party middleware or library code can be written against this generic API and not constrain users to a specific implementation choice.

Usage

use opentelemetry::api::trace::{TracerProvider, Tracer};
use opentelemetry::api::metrics::{Meter, MeterProvider};
use opentelemetry::global;

fn init_tracer() -> global::TracerProviderGuard {
    let provider = opentelemetry::api::trace::NoopTracerProvider::new();

    // Configure the global `TracerProvider` singleton when your app starts
    // (there is a no-op default if this is not set by your application)
    global::set_tracer_provider(provider)
}

fn do_something_tracked() {
    // Then you can use the global provider to create a tracer via `tracer`.
    let _span = global::tracer("my-component").start("span-name");

    // You can also get the tracer via name and version.
    let _tracer = global::tracer_with_version("another-component", "1.1.1");

    // Or access the configured provider via `tracer_provider`.
    let provider = global::tracer_provider();
    let _tracer_a = provider.get_tracer("my-component-a", None);
    let _tracer_b = provider.get_tracer("my-component-b", None);
}

// in main or other app start
let _guard = init_tracer();
do_something_tracked();

Implementation

This module provides types for working with the Open Telemetry API in an abstract implementation-agnostic way through the use of trait objects. There is a performance penalty due to global synchronization as well as heap allocation and dynamic dispatch (e.g. Box<DynSpan> vs sdk::Span), but for many applications this overhead is likely either insignificant or unavoidable as it is in the case of 3rd party integrations that do not know the span type at compile time.

Generic interface

The generic interface is provided by the GlobalProvider struct which can be accessed anywhere via tracer_provider and allows applications to use the BoxedTracer and BoxedSpan instances that implement Tracer and Span. They wrap a boxed dyn GenericProvider, GenericTracer, and Span respectively allowing the underlying implementation to be set at runtime.

Structs

TracerProviderGuard

Restores the previous tracer provider on drop.

Traits

GenericProvider

Allows a specific TracerProvider to be used generically by the GlobalProvider by mirroring the interface and boxing the return types.

Functions

get_text_map_propagator	Executes a closure with a reference to the current global TextMapPropagator propagator.
set_text_map_propagator	Sets the given TextMapPropagator propagator as the current global propagator.
set_tracer_provider	Sets the given TracerProvider instance as the current global provider.
tracer	Creates a named instance of Tracer via the configured GlobalProvider.
tracer_provider	Returns an instance of the currently configured global TracerProvider through GlobalProvider.
tracer_with_version	Creates a named instance of Tracer with version info via the configured GlobalProvider