Module opentelemetry::global
source · Expand description
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
Span
s. 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, noop::NoopTracerProvider};
use opentelemetry::global;
fn init_tracer() {
// Swap this no-op provider for your tracing service of choice (jaeger, zipkin, etc)
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
init_tracer();
do_something_tracked();
§Usage in Libraries
use opentelemetry::trace::{Tracer, TracerProvider};
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_provider().tracer_builder("my-library-name").
with_version(env!("CARGO_PKG_VERSION")).
with_schema_url("https://opentelemetry.io/schemas/1.17.0").
build();
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 and libraries
Applications and libraries can obtain meter from the global meter provider, and use the meter to create instruments to emit measurements.
use opentelemetry::metrics::{Meter};
use opentelemetry::{global, KeyValue};
fn do_something_instrumented() {
let meter = global::meter("my-component");
// It is recommended to reuse the same counter instance for the
// lifetime of the application
let counter = meter.u64_counter("my_counter").init();
// record measurements
counter.add(1, &[KeyValue::new("mykey", "myvalue")]);
}
}
§Usage in Applications
Application owners have the responsibility to set the global meter provider.
The global meter provider can be set using the set_meter_provider
function.
As set_meter_provider takes ownership of the provider, it is recommended to
provide a clone of the provider, if the application needs to use the provider
later to perform operations like shutdown.
use opentelemetry::{global, KeyValue};
fn main() {
// Set the global meter provider
// global::set_meter_provider(my_meter_provider().clone());
}
Structs§
- BoxedSpan
trace
Wraps theBoxedTracer
’sSpan
so it can be used generically by applications without knowing the underlying type. - BoxedTracer
trace
Wraps theGlobalTracerProvider
’sTracer
so it can be used generically by applications without knowing the underlying type. - GlobalMeterProvider
metrics
Represents the globally configuredMeterProvider
instance for this application. - GlobalTracerProvider
trace
Represents the globally configuredTracerProvider
instance for this application. This allows generic tracing through the returnedBoxedTracer
instances.
Enums§
- Wrapper for error from both tracing and metrics part of open telemetry.
Traits§
- ObjectSafeMeterProvider
metrics
Allows a specific MeterProvider to be used generically by the GlobalMeterProvider by mirroring the interface and boxing the return types. - ObjectSafeSpan
trace
Allows a specificcrate::trace::Span
to be used generically byBoxedSpan
instances by mirroring the interface and boxing the return types. - ObjectSafeTracer
trace
Allows a specificTracer
to be used generically byBoxedTracer
instances by mirroring the interface and boxing the return types. - Allows a specific
TracerProvider
to be used generically by theGlobalTracerProvider
by mirroring the interface and boxing the return types.
Functions§
- Executes a closure with a reference to the current global
TextMapPropagator
propagator. - Handle error using the globally configured error handler.
- meter
metrics
Creates a namedMeter
via the configuredGlobalMeterProvider
. - meter_provider
metrics
Returns an instance of the currently configured globalMeterProvider
throughGlobalMeterProvider
. - meter_with_version
metrics
Creates aMeter
with the name, version and schema url. - Set global error handler.
- set_meter_provider
metrics
Sets the givenMeterProvider
instance as the current global meter provider. - Sets the given
TextMapPropagator
propagator as the current global propagator. - set_tracer_provider
trace
Sets the givenTracerProvider
instance as the current global 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
trace
Creates a named instance ofTracer
via the configuredGlobalTracerProvider
. - tracer_provider
trace
Returns an instance of the currently configured globalTracerProvider
throughGlobalTracerProvider
.