opentelemetry_sdk/lib.rs
1//! Implements the [`SDK`] component of [OpenTelemetry].
2//!
3//! *Compiler support: [requires `rustc` 1.65+][msrv]*
4//!
5//! [`SDK`]: https://opentelemetry.io/docs/specs/otel/overview/#sdk
6//! [OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/
7//! [msrv]: #supported-rust-versions
8//!
9//! # Getting Started
10//!
11//! ```no_run
12//! # #[cfg(feature = "trace")]
13//! # {
14//! use opentelemetry::{global, trace::{Tracer, TracerProvider as _}};
15//! use opentelemetry_sdk::trace::TracerProvider;
16//!
17//! fn main() {
18//! // Choose an exporter like `opentelemetry_stdout::SpanExporter`
19//! # fn example<T: opentelemetry_sdk::export::trace::SpanExporter + 'static>(new_exporter: impl Fn() -> T) {
20//! let exporter = new_exporter();
21//!
22//! // Create a new trace pipeline that prints to stdout
23//! let provider = TracerProvider::builder()
24//! .with_simple_exporter(exporter)
25//! .build();
26//! let tracer = provider.tracer("readme_example");
27//!
28//! tracer.in_span("doing_work", |cx| {
29//! // Traced app logic here...
30//! });
31//!
32//! // Shutdown trace pipeline
33//! global::shutdown_tracer_provider();
34//! # }
35//! }
36//! # }
37//! ```
38//!
39//! See the [examples] directory for different integration patterns.
40//!
41//! See the API [`trace`] module docs for more information on creating and managing
42//! spans.
43//!
44//! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
45//! [`trace`]: https://docs.rs/opentelemetry/latest/opentelemetry/trace/index.html
46//!
47//! # Metrics (Alpha)
48//!
49//! Note: the metrics implementation is **still in progress** and **subject to major
50//! changes**.
51//!
52//! ### Creating instruments and recording measurements
53//!
54//! ```
55//! # #[cfg(feature = "metrics")]
56//! # {
57//! use opentelemetry::{global, KeyValue};
58//!
59//! // get a meter from a provider
60//! let meter = global::meter("my_service");
61//!
62//! // create an instrument
63//! let counter = meter.u64_counter("my_counter").init();
64//!
65//! // record a measurement
66//! counter.add(1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);
67//! # }
68//! ```
69//!
70//! See the [examples] directory for different integration patterns.
71//!
72//! See the API [`metrics`] module docs for more information on creating and
73//! managing instruments.
74//!
75//! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
76//! [`metrics`]: https://docs.rs/opentelemetry/latest/opentelemetry/metrics/index.html
77//!
78//! ## Crate Feature Flags
79//!
80//! The following feature flags can used to control the telemetry signals to use:
81//!
82//! * `trace`: Includes the trace SDK (enabled by default).
83//! * `metrics`: Includes the metrics SDK.
84//! * `logs`: Includes the logs SDK.
85//!
86//! For `trace` the following feature flags are available:
87//!
88//! * `jaeger_remote_sampler`: Enables the [Jaeger remote sampler](https://www.jaegertracing.io/docs/1.53/sampling/).
89//!
90//! For `logs` the following feature flags are available:
91//!
92//! * `logs_level_enabled`: control the log level
93//!
94//! Support for recording and exporting telemetry asynchronously and perform
95//! metrics aggregation can be added via the following flags:
96//!
97//! * `rt-tokio`: Spawn telemetry tasks using [tokio]'s multi-thread runtime.
98//! * `rt-tokio-current-thread`: Spawn telemetry tasks on a separate runtime so that the main runtime won't be blocked.
99//! * `rt-async-std`: Spawn telemetry tasks using [async-std]'s runtime.
100//!
101//! [tokio]: https://crates.io/crates/tokio
102//! [async-std]: https://crates.io/crates/async-std
103#![warn(
104 future_incompatible,
105 missing_debug_implementations,
106 missing_docs,
107 nonstandard_style,
108 rust_2018_idioms,
109 unreachable_pub,
110 unused
111)]
112#![allow(clippy::needless_doctest_main)]
113#![cfg_attr(
114 docsrs,
115 feature(doc_cfg, doc_auto_cfg),
116 deny(rustdoc::broken_intra_doc_links)
117)]
118#![doc(
119 html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo.svg"
120)]
121#![cfg_attr(test, deny(warnings))]
122
123pub mod export;
124mod instrumentation;
125#[cfg(feature = "logs")]
126#[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
127pub mod logs;
128#[cfg(feature = "metrics")]
129#[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]
130pub mod metrics;
131#[cfg(feature = "trace")]
132#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
133pub mod propagation;
134pub mod resource;
135pub mod runtime;
136#[cfg(any(feature = "testing", test))]
137#[cfg_attr(docsrs, doc(cfg(any(feature = "testing", test))))]
138pub mod testing;
139
140#[allow(deprecated)]
141#[cfg(feature = "trace")]
142#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
143pub mod trace;
144
145#[doc(hidden)]
146pub mod util;
147
148pub use instrumentation::{InstrumentationLibrary, Scope};
149#[doc(inline)]
150pub use resource::Resource;