diff --git a/README.md b/README.md index 7c0df1434e..88b72ad978 100644 --- a/README.md +++ b/README.md @@ -157,16 +157,17 @@ Registry](https://opentelemetry.io/ecosystem/registry/?language=rust). ## Supported Rust Versions -OpenTelemetry is built against the latest stable release. The minimum supported -version is 1.70. The current OpenTelemetry version is not guaranteed to build -on Rust versions earlier than the minimum supported version. - -The current stable Rust compiler and the three most recent minor versions -before it will always be supported. For example, if the current stable compiler -version is 1.49, the minimum supported version will not be increased past 1.46, -three minor versions prior. Increasing the minimum supported compiler version -is not considered a semver breaking change as long as doing so complies with -this policy. +Components in this repo are built against the latest stable release. The minimum +supported version of `rustc` is 1.70. Any exceptions to this are noted in +indivual readme files of the corresponding create. Crates are not guaranteed to +build on Rust versions earlier than the minimum supported version. + +The current stable Rust compiler and the three most recent minor versions before +it will always be supported. For example, if the current stable compiler version +is 1.49, the minimum supported version will not be increased past 1.46, three +minor versions prior. Increasing the minimum supported compiler version is not +considered a semver breaking change as long as doing so complies with this +policy. ## Contributing diff --git a/opentelemetry/README.md b/opentelemetry/README.md index 5ed786ffcb..29556f096e 100644 --- a/opentelemetry/README.md +++ b/opentelemetry/README.md @@ -21,20 +21,14 @@ vendor- and tool-agnostic, meaning that it can be used with a broad variety of Observability backends, including open source tools like [Jaeger] and [Prometheus], as well as commercial offerings. -OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other -commercial vendors. OpenTelemetry is focused on the generation, collection, -management, and export of telemetry. A major goal of OpenTelemetry is that you -can easily instrument your applications or systems, no matter their language, -infrastructure, or runtime environment. Crucially, the storage and visualization -of telemetry is intentionally left to other tools. +OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or +other commercial vendors. OpenTelemetry is focused on the generation, +collection, management, and export of telemetry. A major goal of OpenTelemetry +is that you can easily instrument your applications or systems, no matter their +language, infrastructure, or runtime environment. Crucially, the storage and +visualization of telemetry is intentionally left to other tools. -*[Supported Rust Versions](#supported-rust-versions)* - -[Prometheus]: https://prometheus.io -[Jaeger]: https://www.jaegertracing.io -[msrv]: #supported-rust-versions - -### What does this crate contain? +## What does this crate contain? This crate is basic foundation for integrating OpenTelemetry into libraries and applications, encompassing several aspects of OpenTelemetry, such as context @@ -44,32 +38,32 @@ specification](https://github.com/open-telemetry/opentelemetry-specification). Here's a breakdown of its components: - **[Context - API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):** - Provides a way to manage and propagate context, which is essential for keeping - track of trace execution across asynchronous tasks. + API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):** + Provides a way to manage and propagate context, which is essential for keeping + track of trace execution across asynchronous tasks. - **[Propagators - API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):** - Defines how context can be shared across process boundaries, ensuring - continuity across microservices or distributed systems. + API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):** + Defines how context can be shared across process boundaries, ensuring + continuity across microservices or distributed systems. - **[Baggage - API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):** - Allows for the attachment of metadata (baggage) to telemetry, which can be - used for sharing application-specific information across service boundaries. + API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):** + Allows for the attachment of metadata (baggage) to telemetry, which can be + used for sharing application-specific information across service boundaries. - **[Logs Bridge - API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/api.md):** - Allows to bridge existing logging mechanisms with OpenTelemetry logging. This - is **NOT** meant for end users to call, instead it is meant to enable writing - bridges/appenders for existing logging mechanisms such as - [log](https://crates.io/crates/log) or - [tracing](https://crates.io/crates/tracing). + API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/api.md):** + Allows to bridge existing logging mechanisms with OpenTelemetry logging. This + is **NOT** meant for end users to call, instead it is meant to enable writing + bridges/appenders for existing logging mechanisms such as + [log](https://crates.io/crates/log) or + [tracing](https://crates.io/crates/tracing). - **[Tracing - API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):** - Offers a set of primitives to produce distributed traces to understand the - flow of a request across system boundaries. + API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):** + Offers a set of primitives to produce distributed traces to understand the + flow of a request across system boundaries. - **[Metrics - API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):** - Offers a set of primitives to produce measurements of operational metrics like - latency, throughput, or error rates. + API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):** + Offers a set of primitives to produce measurements of operational metrics like + latency, throughput, or error rates. This crate serves as a facade or no-op implementation, meaning it defines the traits for instrumentation but does not itself implement the processing or @@ -90,7 +84,7 @@ also aligned with the design philosophy of existing telemetry solutions in the Rust ecosystem, like `tracing` or `log`, where these crates only offer a facade and the actual functionality is enabled through additional crates. -### Related crates +## Related crates Unless you are a library author, you will almost always need to use additional crates along with this. Given this crate has no-op implementation only, an @@ -103,22 +97,22 @@ Additionally one or more exporters are also required to export telemetry to a destination. OpenTelemetry provides the following exporters: - **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):** - Prints telemetry to stdout, primarily used for learning/debugging purposes. + Prints telemetry to stdout, primarily used for learning/debugging purposes. - **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports - telemetry (logs, metrics and traces) in the [OTLP - format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol) - to an endpoint accepting OTLP. This could be the [OTel - Collector](https://github.com/open-telemetry/opentelemetry-collector), - telemetry backends like [Jaeger](https://www.jaegertracing.io/), - [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver) - or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/). + telemetry (logs, metrics and traces) in the [OTLP + format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol) + to an endpoint accepting OTLP. This could be the [OTel + Collector](https://github.com/open-telemetry/opentelemetry-collector), + telemetry backends like [Jaeger](https://www.jaegertracing.io/), + [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver) + or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/). - **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):** - Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin - specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md) + Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin + specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md) - **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):** - Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to - Prometheus - specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md) + Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to + Prometheus + specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md) OpenTelemetry Rust also has a [contrib repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where @@ -126,19 +120,19 @@ additional exporters could be found. Check [OpenTelemetry Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for additional exporters and other related components as well. -## Getting started - -See [docs](https://docs.rs/opentelemetry). - ## Supported Rust Versions -OpenTelemetry is built against the latest stable release. The minimum supported -version is 1.70. The current OpenTelemetry version is not guaranteed to build -on Rust versions earlier than the minimum supported version. +This crate is built against the latest stable release. The minimum supported +version is 1.70. The current version is not guaranteed to build on Rust versions +earlier than the minimum supported version. The current stable Rust compiler and the three most recent minor versions -before it will always be supported. For example, if the current stable compiler -version is 1.49, the minimum supported version will not be increased past 1.46, -three minor versions prior. Increasing the minimum supported compiler version -is not considered a semver breaking change as long as doing so complies with -this policy. +before it will always be supported. For example, if the current stable +compiler version is 1.49, the minimum supported version will not be +increased past 1.46, three minor versions prior. Increasing the minimum +supported compiler version is not considered a semver breaking change as +long as doing so complies with this policy. + +## Usage + +See [docs](https://docs.rs/opentelemetry). diff --git a/opentelemetry/src/lib.rs b/opentelemetry/src/lib.rs index 0e4dd54fc9..4fb3296fa4 100644 --- a/opentelemetry/src/lib.rs +++ b/opentelemetry/src/lib.rs @@ -1,10 +1,118 @@ //! Implements the [`API`] component of [OpenTelemetry]. //! -//! *[Supported Rust Versions](#supported-rust-versions)* -//! //! [`API`]: https://opentelemetry.io/docs/specs/otel/overview/#api //! [OpenTelemetry]: https://opentelemetry.io/docs/what-is-opentelemetry/ //! +//! [Jaeger]: https://www.jaegertracing.io/ +//! [Prometheus]: https://www.prometheus.io/ +//! +//! # Overview + +//! OpenTelemetry is an Observability framework and toolkit designed to create and +//! manage telemetry data such as traces, metrics, and logs. OpenTelemetry is +//! vendor- and tool-agnostic, meaning that it can be used with a broad variety of +//! Observability backends, including open source tools like [Jaeger] and +//! [Prometheus], as well as commercial offerings. + +//! OpenTelemetry is *not* an observability backend like Jaeger, Prometheus, or other +//! commercial vendors. OpenTelemetry is focused on the generation, collection, +//! management, and export of telemetry. A major goal of OpenTelemetry is that you +//! can easily instrument your applications or systems, no matter their language, +//! infrastructure, or runtime environment. Crucially, the storage and visualization +//! of telemetry is intentionally left to other tools. +//! +//! ## What does this crate contain? + +//! This crate is basic foundation for integrating OpenTelemetry into libraries and +//! applications, encompassing several aspects of OpenTelemetry, such as context +//! management and propagation, baggage, logging, tracing, and metrics. It follows +//! the [OpenTelemetry +//! specification](https://github.com/open-telemetry/opentelemetry-specification). +//! Here's a breakdown of its components: +//! +//! - **[Context +//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md):** +//! Provides a way to manage and propagate context, which is essential for keeping +//! track of trace execution across asynchronous tasks. +//! - **[Propagators +//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md):** +//! Defines how context can be shared across process boundaries, ensuring +//! continuity across microservices or distributed systems. +//! - **[Baggage +//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md):** +//! Allows for the attachment of metadata (baggage) to telemetry, which can be +//! used for sharing application-specific information across service boundaries. +//! - **[Logs Bridge +//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/api.md):** +//! Allows to bridge existing logging mechanisms with OpenTelemetry logging. This +//! is **NOT** meant for end users to call, instead it is meant to enable writing +//! bridges/appenders for existing logging mechanisms such as +//! [log](https://crates.io/crates/log) or +//! [tracing](https://crates.io/crates/tracing). +//! - **[Tracing +//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md):** +//! Offers a set of primitives to produce distributed traces to understand the +//! flow of a request across system boundaries. +//! - **[Metrics +//! API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md):** +//! Offers a set of primitives to produce measurements of operational metrics like +//! latency, throughput, or error rates. +//! +//! This crate serves as a facade or no-op implementation, meaning it defines the +//! traits for instrumentation but does not itself implement the processing or +//! exporting of telemetry data. This separation of concerns allows library authors +//! to depend on the API crate without tying themselves to a specific +//! implementation. +//! +//! Actual implementation and the heavy lifting of telemetry data collection, +//! processing, and exporting are delegated to the +//! [opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) crate and +//! various exporter crates such as +//! [opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). This +//! architecture ensures that the final application can light up the instrumentation +//! by integrating an SDK implementation. +//! +//! Library authors are recommended to depend on this crate *only*. This approach is +//! also aligned with the design philosophy of existing telemetry solutions in the +//! Rust ecosystem, like `tracing` or `log`, where these crates only offer a facade +//! and the actual functionality is enabled through additional crates. +//! +//! ## Related crates + +//! Unless you are a library author, you will almost always need to use additional +//! crates along with this. Given this crate has no-op implementation only, an +//! OpenTelemetry SDK is always required. +//! [opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk) is the official +//! SDK implemented by OpenTelemetry itself, though it is possible to use a +//! different sdk. +//! +//! Additionally one or more exporters are also required to export telemetry to a +//! destination. OpenTelemetry provides the following exporters: +//! +//! - **[opentelemetry-stdout](https://crates.io/crates/opentelemetry-stdout):** +//! Prints telemetry to stdout, primarily used for learning/debugging purposes. +//! - **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** Exports +//! telemetry (logs, metrics and traces) in the [OTLP +//! format](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/protocol) +//! to an endpoint accepting OTLP. This could be the [OTel +//! Collector](https://github.com/open-telemetry/opentelemetry-collector), +//! telemetry backends like [Jaeger](https://www.jaegertracing.io/), +//! [Prometheus](https://prometheus.io/docs/prometheus/latest/feature_flags/#otlp-receiver) +//! or [vendor specific endpoints](https://opentelemetry.io/ecosystem/vendors/). +//! - **[opentelemetry-zipkin](https://crates.io/crates/opentelemetry-zipkin):** +//! Exports telemetry (traces only) to Zipkin following [OpenTelemetry to Zipkin +//! specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk_exporters/zipkin.md) +//! - **[opentelemetry-prometheus](https://crates.io/crates/opentelemetry-prometheus):** +//! Exports telemetry (metrics only) to Prometheus following [OpenTelemetry to +//! Prometheus +//! specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/prometheus.md) +//! +//! OpenTelemetry Rust also has a [contrib +//! repo](https://github.com/open-telemetry/opentelemetry-rust-contrib), where +//! additional exporters could be found. Check [OpenTelemetry +//! Registry](https://opentelemetry.io/ecosystem/registry/?language=rust) for +//! additional exporters and other related components as well. +//! //! # Getting Started //! //! ```no_run @@ -24,7 +132,7 @@ //! //! [examples]: https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples //! -//! # Traces +//! ## Traces //! //! The [`trace`] module includes types for tracking the progression of a single //! request while it is handled by services that make up an application. A trace @@ -32,7 +140,7 @@ //! by individual services or components involved in a request as it flows //! through a system. //! -//! ### Creating and exporting spans +//! ### Creating spans //! //! ``` //! # #[cfg(feature = "trace")] @@ -60,7 +168,7 @@ //! //! [`Span`]: crate::trace::Span //! -//! # Metrics +//! ## Metrics //! //! //! The [`metrics`] module includes types for recording measurements about a @@ -88,7 +196,7 @@ //! managing instruments. //! //! -//! # Logs +//! ## Logs //! //! The [`logs`] module contains the Logs Bridge API. It is not intended to be //! called by application developers directly. It is provided for logging @@ -102,15 +210,16 @@ //! [`opentelemetry-appender-tracing`](https://crates.io/crates/opentelemetry-appender-tracing) //! crates. //! -//! ## Crate Feature Flags +//! ## Feature Flags //! //! The following core crate feature flags are available: //! //! * `trace`: Includes the trace API. //! * `metrics`: Includes the metrics API. //! * `logs`: Includes the logs bridge API. +//! * `internal-logs`: Enables internal logging via `tracing`. //! -//! The default feature flags are ["trace", "metrics", "logs"] +//! The default feature flags are ["trace", "metrics", "logs", "internal-logs"]. //! //! The following feature flags provides additional configuration for `logs`: //! * `spec_unstable_logs_enabled`: Allow users to control the log level @@ -118,32 +227,6 @@ //! The following feature flags enable APIs defined in OpenTelemetry specification that is in experimental phase: //! * `otel_unstable`: Includes unstable APIs. //! -//! ## Related Crates -//! -//! In addition to `opentelemetry`, the [`open-telemetry/opentelemetry-rust`] -//! repository contains several additional crates designed to be used with the -//! `opentelemetry` ecosystem. This includes exporters, samplers, as well as -//! utility and adapter crates to assist in propagating context and -//! instrumenting applications. -//! -//! In particular, the following crates are likely to be of interest: -//! -//! - [`opentelemetry_sdk`] provides the OpenTelemetry SDK used to configure providers. -//! - [`opentelemetry-http`] provides an interface for injecting and extracting -//! trace information from [`http`] headers. -//! - [`opentelemetry-otlp`] exporter for sending telemetry in the -//! OTLP format. -//! - [`opentelemetry-prometheus`] provides a pipeline and exporter for sending -//! metrics information to [`Prometheus`]. -//! - [`opentelemetry-zipkin`] provides a pipeline and exporter for sending -//! trace information to [`Zipkin`]. -//! -//! In addition, there are several other useful crates in the [OTel Rust -//! Contrib -//! repo](https://github.com/open-telemetry/opentelemetry-rust-contrib). A lot -//! of crates maintained outside OpenTelemetry owned repos can be found in the -//! [OpenTelemetry -//! Registry](https://opentelemetry.io/ecosystem/registry/?language=rust). //! //! [`http`]: https://crates.io/crates/http //! [`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust @@ -155,19 +238,6 @@ //! [`Prometheus`]: https://prometheus.io //! [`Zipkin`]: https://zipkin.io //! -//! ## Supported Rust Versions -//! -//! OpenTelemetry is built against the latest stable release. The minimum -//! supported version is 1.70. The current OpenTelemetry version is not -//! guaranteed to build on Rust versions earlier than the minimum supported -//! version. -//! -//! The current stable Rust compiler and the three most recent minor versions -//! before it will always be supported. For example, if the current stable -//! compiler version is 1.49, the minimum supported version will not be -//! increased past 1.46, three minor versions prior. Increasing the minimum -//! supported compiler version is not considered a semver breaking change as -//! long as doing so complies with this policy. #![warn( future_incompatible, missing_debug_implementations,