Module opentelemetry::global

Utilities for working with global telemetry primitives

Global Trace API

The global trace 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 while not manually passing 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 in Applications

Applications configure their tracer either by installing a trace pipeline, or calling set_tracer_provider.

use opentelemetry::trace::{Tracer, NoopTracerProvider};
use opentelemetry::global;

fn init_tracer() {
    let provider = 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)
    let _ = global::set_tracer_provider(provider);
}

fn do_something_tracked() {
    // Then you can get a named tracer instance anywhere in your codebase.
    let tracer = global::tracer("my-component");

    tracer.in_span("doing_work", |cx| {
        // Traced app logic here...
    });
}

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

Usage in Libraries

use opentelemetry::trace::Tracer;
use opentelemetry::global;

pub fn my_traced_library_function() {
    // End users of your library will configure their global tracer provider
    // so you can use the global tracer without any setup
    let tracer = global::tracer_with_version("my-library-name", env!("CARGO_PKG_VERSION"));

    tracer.in_span("doing_library_work", |cx| {
        // Traced library logic here...
    });
}

Global Metrics API

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

Usage in Applications

Applications configure their meter either by installing a metrics pipeline, or calling set_meter_provider.

use opentelemetry::metrics::{Meter, noop::NoopMeterProvider};
use opentelemetry::{global, KeyValue};

fn init_meter() {
    let provider = NoopMeterProvider::new();

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

fn do_something_instrumented() {
    // Then you can get a named tracer instance anywhere in your codebase.
    let meter = global::meter("my-component");
    let counter = meter.u64_counter("my_counter").init();

    // record metrics
    counter.add(1, &[KeyValue::new("mykey", "myvalue")]);
}

// in main or other app start
init_meter();
do_something_instrumented();

Usage in Libraries

use opentelemetry::{global, KeyValue};

pub fn my_traced_library_function() {
    // End users of your library will configure their global meter provider
    // so you can use the global meter without any setup
    let tracer = global::meter("my-library-name");
    let counter = tracer.u64_counter("my_counter").init();

    // record metrics
    counter.add(1, &[KeyValue::new("mykey", "myvalue")]);
}

Structs

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

Enums

Error

Wrapper for error from both tracing and metrics part of open telemetry.

Traits

GenericTracer	Allows a specific Tracer to be used generically by BoxedTracer instances by mirroring the interface and boxing the return types.
GenericTracerProvider	Allows a specific TracerProvider to be used generically by the GlobalTracerProvider by mirroring the interface and boxing the return types.

Functions

force_flush_tracer_provider	Force flush all remaining spans in span processors.
get_text_map_propagator	Executes a closure with a reference to the current global TextMapPropagator propagator.
handle_error	Handle error using the globally configured error handler.
meter	Creates a named Meter via the configured GlobalMeterProvider.
meter_provider	Returns an instance of the currently configured global MeterProvider through GlobalMeterProvider.
meter_with_version	Creates a Meter with the name and version.
set_error_handler	Set global error handler.
set_meter_provider	Sets the given MeterProvider instance as the current global meter provider.
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.
shutdown_tracer_provider	Shut down the current tracer provider. This will invoke the shutdown method on all span processors. span processors should export remaining spans before return
tracer	Creates a named instance of Tracer via the configured GlobalTracerProvider.
tracer_provider	Returns an instance of the currently configured global TracerProvider through GlobalTracerProvider.
tracer_with_version	Creates a named instance of Tracer with version info via the configured GlobalTracerProvider