opentelemetry/global/mod.rs
1//! Utilities for working with global telemetry primitives
2//!
3//! ## Global Trace API
4//!
5//! The global trace API **provides applications access to their configured
6//! [`TracerProvider`] instance from anywhere in the codebase**. This allows
7//! applications to be less coupled to the specific Open Telemetry SDK while not
8//! manually passing references to each part of the code that needs to create
9//! [`Span`]s. Additionally, **3rd party middleware** or **library code** can be
10//! written against this generic API and not constrain users to a specific
11//! implementation choice.
12//!
13//! ### Usage in Applications
14//!
15//! Applications configure their tracer either by installing a trace pipeline,
16//! or calling [`set_tracer_provider`].
17//!
18//! ```
19//! # #[cfg(feature="trace")]
20//! # {
21//! use opentelemetry::trace::{Tracer, noop::NoopTracerProvider};
22//! use opentelemetry::global;
23//!
24//! fn init_tracer() {
25//! // Swap this no-op provider for your tracing service of choice (jaeger, zipkin, etc)
26//! let provider = NoopTracerProvider::new();
27//!
28//! // Configure the global `TracerProvider` singleton when your app starts
29//! // (there is a no-op default if this is not set by your application)
30//! let _ = global::set_tracer_provider(provider);
31//! }
32//!
33//! fn do_something_tracked() {
34//! // Then you can get a named tracer instance anywhere in your codebase.
35//! let tracer = global::tracer("my-component");
36//!
37//! tracer.in_span("doing_work", |cx| {
38//! // Traced app logic here...
39//! });
40//! }
41//!
42//! // in main or other app start
43//! init_tracer();
44//! do_something_tracked();
45//! # }
46//! ```
47//!
48//! ### Usage in Libraries
49//!
50//! ```
51//! # #[cfg(feature="trace")]
52//! # {
53//! use opentelemetry::trace::{Tracer, TracerProvider};
54//! use opentelemetry::global;
55//!
56//! pub fn my_traced_library_function() {
57//! // End users of your library will configure their global tracer provider
58//! // so you can use the global tracer without any setup
59//! let tracer = global::tracer_provider().tracer_builder("my-library-name").
60//! with_version(env!("CARGO_PKG_VERSION")).
61//! with_schema_url("https://opentelemetry.io/schemas/1.17.0").
62//! build();
63//!
64//! tracer.in_span("doing_library_work", |cx| {
65//! // Traced library logic here...
66//! });
67//! }
68//! # }
69//! ```
70//!
71//! [`TracerProvider`]: crate::trace::TracerProvider
72//! [`Span`]: crate::trace::Span
73//!
74//! ## Global Metrics API
75//!
76//! The global metrics API **provides applications access to their configured
77//! [`MeterProvider`] instance from anywhere in the codebase**. This allows
78//! applications to be less coupled to the specific Open Telemetry SDK while not
79//! manually passing references to each part of the code that needs to create
80//! metric instruments. Additionally, **3rd party middleware** or **library code** can be
81//! written against this generic API and not constrain users to a specific
82//! implementation choice.
83//!
84//! ### Usage in Applications and libraries
85//!
86//! Applications and libraries can obtain meter from the global meter provider,
87//! and use the meter to create instruments to emit measurements.
88//!
89//! ```
90//! # #[cfg(feature="metrics")]
91//! # {
92//! use opentelemetry::metrics::{Meter};
93//! use opentelemetry::{global, KeyValue};
94//!
95//! fn do_something_instrumented() {
96//! let meter = global::meter("my-component");
97//! // It is recommended to reuse the same counter instance for the
98//! // lifetime of the application
99//! let counter = meter.u64_counter("my_counter").init();
100//!
101//! // record measurements
102//! counter.add(1, &[KeyValue::new("mykey", "myvalue")]);
103//! }
104//! }
105//! ```
106//!
107//! ### Usage in Applications
108//! Application owners have the responsibility to set the global meter provider.
109//! The global meter provider can be set using the [`set_meter_provider`] function.
110//! As set_meter_provider takes ownership of the provider, it is recommended to
111//! provide a clone of the provider, if the application needs to use the provider
112//! later to perform operations like shutdown.
113//! ```
114//! # #[cfg(feature="metrics")]
115//! # {
116//! use opentelemetry::{global, KeyValue};
117//!
118//! fn main() {
119//! // Set the global meter provider
120//! // global::set_meter_provider(my_meter_provider().clone());
121//! }
122//! # }
123//! ```
124//!
125//! [`MeterProvider`]: crate::metrics::MeterProvider
126//! [`set_meter_provider`]: crate::global::set_meter_provider
127
128mod error_handler;
129#[cfg(feature = "metrics")]
130mod metrics;
131#[cfg(feature = "trace")]
132mod propagation;
133#[cfg(feature = "trace")]
134mod trace;
135
136pub use error_handler::{handle_error, set_error_handler, Error};
137#[cfg(feature = "metrics")]
138#[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]
139pub use metrics::*;
140#[cfg(feature = "trace")]
141#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
142pub use propagation::*;
143#[cfg(feature = "trace")]
144#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
145pub use trace::*;