Skip to content

Commit 45b0963

Browse files
jtescherjtescher
authored
Update global docs and split out feature flag docs (#344)
1 parent 3e1948e commit 45b0963

File tree

2 files changed

+136
-56
lines changed

2 files changed

+136
-56
lines changed

‎opentelemetry/src/global/mod.rs

Lines changed: 108 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,133 @@
1-
//! # OpenTelemetry Global API
1+
//! Utilities for working with global telemetry primitives
22
//!
3-
//! The global API **provides applications access to their configured
3+
//! ## Global Trace API
4+
//!
5+
//! The global trace API **provides applications access to their configured
46
//! [`TracerProvider`] instance from anywhere in the codebase**. This allows
5-
//! applications to be less coupled to the specific Open Telemetry SDK as
6-
//! well as not manually pass references to each part of the code that needs
7-
//! to create [`Span`]s. Additionally, **3rd party middleware** or **library code**
8-
//! can be written against this generic API and not constrain users to a
9-
//! specific implementation choice.
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
1014
//!
11-
//! ## Usage
15+
//! Applications configure their tracer either by [installing a trace pipeline],
16+
//! or calling [`set_tracer_provider`].
1217
//!
13-
//! ```ignore
14-
//! use opentelemetry::trace::{Tracer, TracerProvider};
15-
//! use opentelemetry::metrics::{Meter, MeterProvider};
18+
//! ```
19+
//! use opentelemetry::trace::{Tracer, NoopTracerProvider};
1620
//! use opentelemetry::global;
1721
//!
1822
//! fn init_tracer() -> global::TracerProviderGuard {
19-
//! let provider = opentelemetry::trace::NoopTracerProvider::new();
23+
//! let provider = NoopTracerProvider::new();
2024
//!
2125
//! // Configure the global `TracerProvider` singleton when your app starts
2226
//! // (there is a no-op default if this is not set by your application)
2327
//! global::set_tracer_provider(provider)
2428
//! }
2529
//!
2630
//! fn do_something_tracked() {
27-
//! // Then you can use the global provider to create a tracer via `tracer`.
28-
//! let _span = global::tracer("my-component").start("span-name");
31+
//! // Then you can get a named tracer instance anywhere in your codebase.
32+
//! let tracer = global::tracer("my-component");
2933
//!
30-
//! // You can also get the tracer via name and version.
31-
//! let _tracer = global::tracer_with_version("another-component", "1.1.1");
32-
//!
33-
//! // Or access the configured provider via `tracer_provider`.
34-
//! let provider = global::tracer_provider();
35-
//! let _tracer_a = provider.get_tracer("my-component-a", None);
36-
//! let _tracer_b = provider.get_tracer("my-component-b", None);
34+
//! tracer.in_span("doing_work", |cx| {
35+
//! // Traced app logic here...
36+
//! });
3737
//! }
3838
//!
3939
//! // in main or other app start
4040
//! let _guard = init_tracer();
4141
//! do_something_tracked();
4242
//! ```
4343
//!
44-
//! ## Implementation
45-
//!
46-
//! This module provides types for working with the Open Telemetry API in an
47-
//! abstract implementation-agnostic way through the use of [trait objects].
48-
//! There is a **performance penalty** due to global synchronization as well
49-
//! as heap allocation and dynamic dispatch (e.g. `Box<DynSpan>` vs
50-
//! `sdk::Span`), but for many applications this overhead is likely either
51-
//! insignificant or unavoidable as it is in the case of 3rd party integrations
52-
//! that do not know the span type at compile time.
53-
//!
54-
//! ### Generic interface
55-
//!
56-
//! The generic interface is provided by the [`GlobalProvider`] struct which
57-
//! can be accessed anywhere via [`tracer_provider`] and allows applications to
58-
//! use the [`BoxedTracer`] and [`BoxedSpan`] instances that implement
59-
//! [`Tracer`] and [`Span`]. They wrap a boxed dyn [`GenericTracerProvider`],
60-
//! [`GenericTracer`], and [`Span`] respectively allowing the underlying
61-
//! implementation to be set at runtime.
62-
//!
63-
//! [`TracerProvider`]: ../api/trace/provider/trait.TracerProvider.html
64-
//! [`Tracer`]: ../api/trace/tracer/trait.Tracer.html
65-
//! [`Span`]: ../api/trace/span/trait.Span.html
66-
//! [`GenericTracerProvider`]: trait.GenericTracerProvider.html
67-
//! [`GenericTracer`]: trait.GenericTracer.html
68-
//! [`GlobalProvider`]: struct.GlobalProvider.html
69-
//! [`BoxedTracer`]: struct.BoxedTracer.html
70-
//! [`BoxedSpan`]: struct.BoxedSpan.html
71-
//! [`tracer_provider`]: fn.tracer_provider.html
72-
//! [trait objects]: https://doc.rust-lang.org/reference/types/trait-object.html#trait-objects
44+
//! ### Usage in Libraries
45+
//!
46+
//! ```
47+
//! use opentelemetry::trace::Tracer;
48+
//! use opentelemetry::global;
49+
//!
50+
//! pub fn my_traced_library_function() {
51+
//! // End users of your library will configure their global tracer provider
52+
//! // so you can use the global tracer without any setup
53+
//! let tracer = global::tracer_with_version("my-library-name", env!("CARGO_PKG_VERSION"));
54+
//!
55+
//! tracer.in_span("doing_library_work", |cx| {
56+
//! // Traced library logic here...
57+
//! });
58+
//! }
59+
//! ```
60+
//!
61+
//! [installing a trace pipeline]: crate::exporter::trace::stdout::PipelineBuilder::install
62+
//! [`TracerProvider`]: crate::trace::TracerProvider
63+
//! [`Span`]: crate::trace::Span
64+
//!
65+
//! ## Global Metrics API
66+
//!
67+
//! The global metrics API **provides applications access to their configured
68+
//! [`MeterProvider`] instance from anywhere in the codebase**. This allows
69+
//! applications to be less coupled to the specific Open Telemetry SDK while not
70+
//! manually passing references to each part of the code that needs to create
71+
//! metric instruments. Additionally, **3rd party middleware** or **library code** can be
72+
//! written against this generic API and not constrain users to a specific
73+
//! implementation choice.
74+
//!
75+
//! ### Usage in Applications
76+
//!
77+
//! Applications configure their tracer either by [installing a metrics pipeline],
78+
//! or calling [`set_meter_provider`].
79+
//!
80+
//! ```
81+
//! # #[cfg(feature="metrics")]
82+
//! # {
83+
//! use opentelemetry::metrics::{Meter, noop::NoopMeterProvider};
84+
//! use opentelemetry::{global, KeyValue};
85+
//!
86+
//! fn init_meter() {
87+
//! let provider = NoopMeterProvider;
88+
//!
89+
//! // Configure the global `MeterProvider` singleton when your app starts
90+
//! // (there is a no-op default if this is not set by your application)
91+
//! global::set_meter_provider(provider)
92+
//! }
93+
//!
94+
//! fn do_something_instrumented() {
95+
//! // Then you can get a named tracer instance anywhere in your codebase.
96+
//! let tracer = global::meter("my-component");
97+
//! let counter = tracer.u64_counter("my_counter").init();
98+
//!
99+
//! // record metrics
100+
//! counter.add(1, &[KeyValue::new("mykey", "myvalue")]);
101+
//! }
102+
//!
103+
//! // in main or other app start
104+
//! init_meter();
105+
//! do_something_instrumented();
106+
//! # }
107+
//! ```
108+
//!
109+
//! ### Usage in Libraries
110+
//!
111+
//! ```
112+
//! # #[cfg(feature="metrics")]
113+
//! # {
114+
//! use opentelemetry::trace::Tracer;
115+
//! use opentelemetry::{global, KeyValue};
116+
//!
117+
//! pub fn my_traced_library_function() {
118+
//! // End users of your library will configure their global meter provider
119+
//! // so you can use the global meter without any setup
120+
//! let tracer = global::meter("my-library-name");
121+
//! let counter = tracer.u64_counter("my_counter").init();
122+
//!
123+
//! // record metrics
124+
//! counter.add(1, &[KeyValue::new("mykey", "myvalue")]);
125+
//! }
126+
//! # }
127+
//! ```
128+
//!
129+
//! [installing a metrics pipeline]: crate::exporter::metrics::stdout::StdoutExporterBuilder::try_init
130+
//! [`MeterProvider`]: crate::metrics::MeterProvider
73131
74132
#[cfg(feature = "metrics")]
75133
mod error_handler;

‎opentelemetry/src/lib.rs

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,37 @@
3232
//!
3333
//! ## Crate Feature Flags
3434
//!
35-
//! The following crate feature flags are available:
35+
//! The following core crate feature flags are available:
3636
//!
3737
//! * `trace`: Includes the trace API and SDK (enabled by default).
3838
//! * `metrics`: Includes the unstable metrics API and SDK.
39-
//! * `base64_format`: Adds experimental support for encoding span context
40-
//! information in base64.
41-
//! * `serialize`: Adds serde serializers for common types.
42-
//! * `binary_propagator`: Adds experimental support for the trace binary
43-
//! propagator.
39+
//! * `serialize`: Adds [serde] serializers for common types.
40+
//!
41+
//! Support for recording and exporting telemetry asynchronously can be added
42+
//! via the following flags:
43+
//!
44+
//! * `tokio`: Spawn telemetry tasks using [tokio]'s runtime.
45+
//! * `async-std`: Spawn telemetry tasks using [async-std]'s runtime.
46+
//!
47+
//! The following flags enable propagating information in other crate
48+
//! ecosystems:
49+
//!
50+
//! * `http`: Propagate information via [http] header maps.
51+
//! * `tonic`: Propagate information via [tonic]'s metadata.
52+
//!
53+
//! Finally the following flags can be used by exporter authors:
54+
//!
55+
//! * `reqwest`: Implementation of [`HttpClient`] for [reqwest].
56+
//! * `surf`: Implementation of [`HttpClient`] for [surf]`.
57+
//!
58+
//! [tokio]: https://crates.io/crates/tokio
59+
//! [async-std]: https://crates.io/crates/async-std
60+
//! [serde]: https://crates.io/crates/serde
61+
//! [http]: https://crates.io/crates/http
62+
//! [tonic]: https://crates.io/crates/tonic
63+
//! [`HttpClient`]: crate::exporter::trace::HttpClient
64+
//! [reqwest]: https://crates.io/crates/reqwest
65+
//! [surf]: https://crates.io/crates/surf
4466
//!
4567
//! ## Related Crates
4668
//!

0 commit comments

Comments
 (0)