Module opentelemetry::global

OpenTelemetry Global API

The global API provides applications access to their configured Provider 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::{Provider, Tracer};
use opentelemetry::global;

fn init_tracer() {
    let provider = opentelemetry::api::NoopProvider {};

    // Configure the global `Provider` singleton when your app starts
    // (there is a no-op default if this is not set by your application)
    global::set_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");

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

// in main or other app start
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 trace_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

BoxedSpan	Wraps the BoxedTracer's Span so it can be used generically by applications without knowing the underlying type.
BoxedTracer	Wraps the GlobalProvider's Tracer so it can be used generically by applications without knowing the underlying type.
GlobalProvider	Represents the globally configured Provider instance for this application. This allows generic tracing through the returned BoxedTracer instances.

Traits

GenericProvider	Allows a specific Provider to be used generically by the GlobalProvider by mirroring the interface and boxing the return types.
GenericTracer	Allows a specific Tracer to be used generically by BoxedTracer instances by mirroring the interface and boxing the return types.

Functions

get_http_text_propagator	Executes a closure with a reference to the current global HttpTextFormat propagator.
global_meter	Returns NoopMeter for now
set_http_text_propagator	Sets the given HttpTextFormat propagator as the current global propagator.
set_provider	Sets the given Provider instance as the current global provider.
trace_provider	Returns an instance of the currently configured global Provider through GlobalProvider.
tracer	Creates a named instance of Tracer via the configured GlobalProvider.