1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
//! # 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 [`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 //! //! ```ignore //! 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. //! //! [`TracerProvider`]: ../api/trace/provider/trait.TracerProvider.html //! [`Tracer`]: ../api/trace/tracer/trait.Tracer.html //! [`Span`]: ../api/trace/span/trait.Span.html //! [`GenericProvider`]: trait.GenericProvider.html //! [`GenericTracer`]: trait.GenericTracer.html //! [`GlobalProvider`]: struct.GlobalProvider.html //! [`BoxedTracer`]: struct.BoxedTracer.html //! [`BoxedSpan`]: struct.BoxedSpan.html //! [`tracer_provider`]: fn.tracer_provider.html //! [trait objects]: https://doc.rust-lang.org/reference/types/trait-object.html#trait-objects #[cfg(feature = "metrics")] mod error_handler; #[cfg(feature = "metrics")] mod metrics; #[cfg(feature = "trace")] mod propagation; #[cfg(feature = "trace")] mod trace; #[cfg(feature = "metrics")] pub use error_handler::{handle_error, set_error_handler}; #[cfg(feature = "metrics")] pub use metrics::{meter, meter_provider, set_meter_provider}; #[cfg(feature = "trace")] pub use propagation::{get_text_map_propagator, set_text_map_propagator}; #[cfg(feature = "trace")] pub use trace::{ set_tracer_provider, tracer, tracer_provider, tracer_with_version, GenericProvider, TracerProviderGuard, };