opentelemetry/
lib.rs

1//! Implements the [`API`] component of [OpenTelemetry].
2//!
3//! *Compiler support: [requires `rustc` 1.64+][msrv]*
4//!
5//! [`API`]: https://opentelemetry.io/docs/specs/otel/overview/#api
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::{TraceContextExt, Tracer}, Context };
15//!
16//! fn do_something() {
17//!     let tracer = global::tracer("my_component");
18//!     let _guard = Context::current_with_span(tracer.start("my_span")).attach();
19//!     // do work tracked by the now current span
20//! }
21//! # }
22//! ```
23//!
24//! See the [examples] directory for different integration patterns.
25//!
26//! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
27//!
28//! # Traces
29//!
30//! The [`trace`] module includes types for tracking the progression of a single
31//! request while it is handled by services that make up an application. A trace
32//! is a tree of [`Span`]s which are objects that represent the work being done
33//! by individual services or components involved in a request as it flows
34//! through a system.
35//!
36//! ### Creating and exporting spans
37//!
38//! ```
39//! # #[cfg(feature = "trace")]
40//! # {
41//! use opentelemetry::{global, trace::{Span, Tracer}, KeyValue};
42//!
43//! // get a tracer from a provider
44//! let tracer = global::tracer("my_service");
45//!
46//! // start a new span
47//! let mut span = tracer.start("my_span");
48//!
49//! // set some attributes
50//! span.set_attribute(KeyValue::new("http.client_ip", "83.164.160.102"));
51//!
52//! // perform some more work...
53//!
54//! // end or drop the span to export
55//! span.end();
56//! # }
57//! ```
58//!
59//! See the [`trace`] module docs for more information on creating and managing
60//! spans.
61//!
62//! [`Span`]: crate::trace::Span
63//!
64//! # Metrics
65//!
66//!
67//! The [`metrics`] module includes types for recording measurements about a
68//! service at runtime.
69//!
70//! ### Creating instruments and recording measurements
71//!
72//! ```
73//! # #[cfg(feature = "metrics")]
74//! # {
75//! use opentelemetry::{global, KeyValue};
76//!
77//! // get a meter from a provider
78//! let meter = global::meter("my_service");
79//!
80//! // create an instrument
81//! let counter = meter.u64_counter("my_counter").init();
82//!
83//! // record a measurement
84//! counter.add(1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);
85//! # }
86//! ```
87//!
88//! See the [`metrics`] module docs for more information on creating and
89//! managing instruments.
90//!
91//!
92//! //! # Logs
93//!
94//!  The [`logs`] module contains the Logs Bridge API. It is not intended to be
95//!  called by application developers directly. It is provided for logging
96//!  library authors to build log appenders, that bridges existing logging
97//!  systems with OpenTelemetry. Bridges for
98//!  [`log`](https://crates.io/crates/log) and
99//!  [`tracing`](https://crates.io/crates/tracing) libraries are provided via
100//!  the
101//!  [`opentelemetry-appender-log`](https://crates.io/crates/opentelemetry-appender-log)
102//!  and
103//!  [`opentelemetry-appender-tracing`](https://crates.io/crates/opentelemetry-appender-tracing)
104//!  crates.
105//!
106//! ## Crate Feature Flags
107//!
108//! The following core crate feature flags are available:
109//!
110//! * `trace`: Includes the trace API (enabled by default).
111//! * `metrics`: Includes the metrics API.
112//! * `logs`: Includes the logs bridge API.
113//!
114//! The following feature flags provides additional configuration for `logs`:
115//! * `logs_level_enabled`: Allow users to control the log level
116//!
117//! The following feature flags enable APIs defined in OpenTelemetry specification that is in experimental phase:
118//! * `otel_unstable`: Includes unstable APIs (enabled by default).
119//!
120//! ## Related Crates
121//!
122//! In addition to `opentelemetry`, the [`open-telemetry/opentelemetry-rust`]
123//! repository contains several additional crates designed to be used with the
124//! `opentelemetry` ecosystem. This includes exporters, samplers, as well as
125//! utility and adapter crates to assist in propagating context and
126//! instrumenting applications.
127//!
128//! In particular, the following crates are likely to be of interest:
129//!
130//! - [`opentelemetry_sdk`] provides the OpenTelemetry SDK used to configure providers.
131//! - [`opentelemetry-http`] provides an interface for injecting and extracting
132//!   trace information from [`http`] headers.
133//! - [`opentelemetry-otlp`] exporter for sending telemetry in the
134//!   OTLP format.
135//! - [`opentelemetry-prometheus`] provides a pipeline and exporter for sending
136//!   metrics information to [`Prometheus`].
137//! - [`opentelemetry-zipkin`] provides a pipeline and exporter for sending
138//!   trace information to [`Zipkin`].
139//!
140//!  In addition, there are several other useful crates in the [OTel Rust
141//!  Contrib
142//!  repo](https://github.com/open-telemetry/opentelemetry-rust-contrib). A lot
143//!  of crates maintained outside OpenTelemetry owned repos can be found in the
144//!  [OpenTelemetry
145//!  Registry](https://opentelemetry.io/ecosystem/registry/?language=rust).
146//!
147//! [`http`]: https://crates.io/crates/http
148//! [`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust
149//! [`opentelemetry_sdk`]: https://crates.io/crates/opentelemetry_sdk
150//! [`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http
151//! [`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp
152//! [`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus
153//! [`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin
154//! [`Prometheus`]: https://prometheus.io
155//! [`Zipkin`]: https://zipkin.io
156//!
157//! ## Supported Rust Versions
158//!
159//! OpenTelemetry is built against the latest stable release. The minimum
160//! supported version is 1.64. The current OpenTelemetry version is not
161//! guaranteed to build on Rust versions earlier than the minimum supported
162//! version.
163//!
164//! The current stable Rust compiler and the three most recent minor versions
165//! before it will always be supported. For example, if the current stable
166//! compiler version is 1.49, the minimum supported version will not be
167//! increased past 1.46, three minor versions prior. Increasing the minimum
168//! supported compiler version is not considered a semver breaking change as
169//! long as doing so complies with this policy.
170#![warn(
171    future_incompatible,
172    missing_debug_implementations,
173    missing_docs,
174    nonstandard_style,
175    rust_2018_idioms,
176    unreachable_pub,
177    unused
178)]
179#![allow(clippy::needless_doctest_main)]
180#![cfg_attr(
181    docsrs,
182    feature(doc_cfg, doc_auto_cfg),
183    deny(rustdoc::broken_intra_doc_links)
184)]
185#![doc(
186    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo.svg"
187)]
188#![cfg_attr(test, deny(warnings))]
189
190pub mod global;
191
192pub mod baggage;
193
194mod context;
195
196pub use context::{Context, ContextGuard};
197
198mod common;
199
200#[cfg(any(feature = "testing", test))]
201#[doc(hidden)]
202pub mod testing;
203
204pub use common::{
205    Array, ExportError, InstrumentationLibrary, InstrumentationLibraryBuilder, Key, KeyValue,
206    StringValue, Value,
207};
208
209#[cfg(feature = "metrics")]
210#[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]
211pub mod metrics;
212
213pub mod propagation;
214
215#[cfg(feature = "trace")]
216#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
217pub mod trace;
218
219#[cfg(feature = "logs")]
220#[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
221pub mod logs;
222
223#[doc(hidden)]
224#[cfg(any(feature = "metrics", feature = "trace"))]
225pub mod time {
226    use std::time::SystemTime;
227
228    #[doc(hidden)]
229    #[cfg(any(
230        not(target_arch = "wasm32"),
231        all(target_arch = "wasm32", target_os = "wasi")
232    ))]
233    pub fn now() -> SystemTime {
234        SystemTime::now()
235    }
236
237    #[doc(hidden)]
238    #[cfg(all(target_arch = "wasm32", not(target_os = "wasi")))]
239    pub fn now() -> SystemTime {
240        SystemTime::UNIX_EPOCH + std::time::Duration::from_millis(js_sys::Date::now() as u64)
241    }
242}