opentelemetry_sdk/
lib.rs

1//! Implements the [`SDK`] component of [OpenTelemetry].
2//!
3//! *[Supported Rust Versions](#supported-rust-versions)*
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}};
15//! use opentelemetry_sdk::trace::SdkTracerProvider;
16//!
17//! fn main() {
18//!     // Choose an exporter like `opentelemetry_stdout::SpanExporter`
19//!     # fn example<T: opentelemetry_sdk::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 = SdkTracerProvider::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//!     provider.shutdown().expect("TracerProvider should shutdown successfully")
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
48//!
49//! ### Creating instruments and recording measurements
50//!
51//! ```
52//! # #[cfg(feature = "metrics")]
53//! # {
54//! use opentelemetry::{global, KeyValue};
55//!
56//! // get a meter from a provider
57//! let meter = global::meter("my_service");
58//!
59//! // create an instrument
60//! let counter = meter.u64_counter("my_counter").build();
61//!
62//! // record a measurement
63//! counter.add(1, &[KeyValue::new("http.client_ip", "83.164.160.102")]);
64//! # }
65//! ```
66//!
67//! See the [examples] directory for different integration patterns.
68//!
69//! See the API [`metrics`] module docs for more information on creating and
70//! managing instruments.
71//!
72//! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples
73//! [`metrics`]: https://docs.rs/opentelemetry/latest/opentelemetry/metrics/index.html
74//!
75//! ## Environment Variables
76//!
77//! The SDK respects the following environment variables, as defined by the
78//! [OpenTelemetry specification]. Programmatic configuration via builder methods
79//! takes precedence over environment variables.
80//!
81//! [OpenTelemetry specification]: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
82//!
83//! ### General / Resource
84//!
85//! | Variable | Description | Default |
86//! |---|---|---|
87//! | `OTEL_SERVICE_NAME` | Sets the value of the `service.name` resource attribute. Takes priority over `service.name` in `OTEL_RESOURCE_ATTRIBUTES`. | `unknown_service:<process_name>` |
88//! | `OTEL_RESOURCE_ATTRIBUTES` | Key-value pairs to be used as resource attributes. Format: `key1=value1,key2=value2`. | (none) |
89//!
90//! ### Trace: Sampler
91//!
92//! | Variable | Description | Default |
93//! |---|---|---|
94//! | `OTEL_TRACES_SAMPLER` | Sampler to use. Valid values: `always_on`, `always_off`, `traceidratio`, `parentbased_always_on`, `parentbased_always_off`, `parentbased_traceidratio`. | `parentbased_always_on` |
95//! | `OTEL_TRACES_SAMPLER_ARG` | Argument for the sampler. Used when `OTEL_TRACES_SAMPLER` is `traceidratio` or `parentbased_traceidratio`. Must be a float between 0.0 and 1.0. | `1.0` |
96//!
97//! ### Trace: Span Limits
98//!
99//! | Variable | Description | Default |
100//! |---|---|---|
101//! | `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` | Maximum number of attributes allowed on a span. | `128` |
102//! | `OTEL_SPAN_EVENT_COUNT_LIMIT` | Maximum number of events allowed on a span. | `128` |
103//! | `OTEL_SPAN_LINK_COUNT_LIMIT` | Maximum number of links allowed on a span. | `128` |
104//!
105//! ### Trace: Batch Span Processor (BSP)
106//!
107//! | Variable | Description | Default |
108//! |---|---|---|
109//! | `OTEL_BSP_SCHEDULE_DELAY` | Delay interval (in milliseconds) between two consecutive exports. | `5000` |
110//! | `OTEL_BSP_MAX_QUEUE_SIZE` | Maximum queue size. | `2048` |
111//! | `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | Maximum batch size. Must be less than or equal to `OTEL_BSP_MAX_QUEUE_SIZE`. | `512` |
112//! | `OTEL_BSP_MAX_CONCURRENT_EXPORTS` | Maximum number of concurrent exports. Honored by `span_processor_with_async_runtime::BatchSpanProcessor`; thread-based `BatchSpanProcessor` exports serially. For concurrent exports, enable `experimental_trace_batch_span_processor_with_async_runtime` and use the async-runtime processor. | `1` |
113//!
114//! ### Logs: Batch Log Record Processor (BLRP)
115//!
116//! | Variable | Description | Default |
117//! |---|---|---|
118//! | `OTEL_BLRP_SCHEDULE_DELAY` | Delay interval (in milliseconds) between two consecutive exports. | `1000` |
119//! | `OTEL_BLRP_MAX_QUEUE_SIZE` | Maximum queue size. | `2048` |
120//! | `OTEL_BLRP_MAX_EXPORT_BATCH_SIZE` | Maximum batch size. Must be less than or equal to `OTEL_BLRP_MAX_QUEUE_SIZE`. | `512` |
121//!
122//! ### Metrics: Periodic Metric Reader
123//!
124//! | Variable | Description | Default |
125//! |---|---|---|
126//! | `OTEL_METRIC_EXPORT_INTERVAL` | Interval (in milliseconds) between metrics exports. | `60000` |
127//!
128//! ## Crate Feature Flags
129//!
130//! The following feature flags can used to control the telemetry signals to use:
131//!
132//! * `trace`: Includes the trace SDK (enabled by default).
133//! * `metrics`: Includes the metrics SDK (enabled by default).
134//! * `logs`: Includes the logs SDK (enabled by default).
135//!
136//! For `trace` the following feature flags are available:
137//!
138//! * `jaeger_remote_sampler`: Enables the [Jaeger remote sampler](https://www.jaegertracing.io/docs/1.53/sampling/).
139//!
140//!
141//! Support for recording and exporting telemetry asynchronously and perform
142//! metrics aggregation can be added via the following flags:
143//!
144//! * `experimental_async_runtime`: Enables the experimental `Runtime` trait and related functionality.
145//! * `rt-tokio`: Spawn telemetry tasks using [tokio]'s multi-thread runtime.
146//! * `rt-tokio-current-thread`: Spawn telemetry tasks on a separate runtime so that the main runtime won't be blocked.
147//!
148//! [tokio]: https://crates.io/crates/tokio
149#![warn(
150    future_incompatible,
151    missing_debug_implementations,
152    missing_docs,
153    nonstandard_style,
154    rust_2018_idioms,
155    unreachable_pub,
156    unused
157)]
158#![allow(clippy::needless_doctest_main)]
159#![cfg_attr(docsrs, feature(doc_cfg), deny(rustdoc::broken_intra_doc_links))]
160#![doc(
161    html_logo_url = "https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo.svg"
162)]
163#![cfg_attr(test, deny(warnings))]
164
165pub(crate) mod growable_array;
166
167#[cfg(feature = "logs")]
168#[cfg_attr(docsrs, doc(cfg(feature = "logs")))]
169pub mod logs;
170#[cfg(feature = "metrics")]
171#[cfg_attr(docsrs, doc(cfg(feature = "metrics")))]
172pub mod metrics;
173#[cfg(feature = "trace")]
174#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
175pub mod propagation;
176pub mod resource;
177#[cfg(feature = "experimental_async_runtime")]
178pub mod runtime;
179#[cfg(any(feature = "testing", test))]
180#[cfg_attr(docsrs, doc(cfg(any(feature = "testing", test))))]
181pub mod testing;
182
183#[cfg(feature = "trace")]
184#[cfg_attr(docsrs, doc(cfg(feature = "trace")))]
185pub mod trace;
186
187#[doc(hidden)]
188pub mod util;
189
190#[doc(inline)]
191pub use resource::Resource;
192
193pub mod error;
194pub use error::ExportError;
opentelemetry_sdk/lib.rs

opentelemetry_sdk/
lib.rs
