From 9cd2c44123de00b0f7579d36b7ffa9ea5e47f954 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 27 Feb 2024 11:31:23 -0800 Subject: [PATCH 1/2] Rewrite readme page for opentelemetry crate --- opentelemetry/Cargo.toml | 2 +- opentelemetry/README.md | 161 ++++++++++----------------------------- 2 files changed, 42 insertions(+), 121 deletions(-) diff --git a/opentelemetry/Cargo.toml b/opentelemetry/Cargo.toml index 1d65098091..7e0b73600d 100644 --- a/opentelemetry/Cargo.toml +++ b/opentelemetry/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "opentelemetry" version = "0.22.0" -description = "A metrics collection and distributed tracing framework" +description = "OpenTelemetry API for Rust" homepage = "https://github.com/open-telemetry/opentelemetry-rust" repository = "https://github.com/open-telemetry/opentelemetry-rust" readme = "README.md" diff --git a/opentelemetry/README.md b/opentelemetry/README.md index 3263fbe098..6b85245b89 100644 --- a/opentelemetry/README.md +++ b/opentelemetry/README.md @@ -1,10 +1,6 @@ -![OpenTelemetry — An observability framework for cloud-native software.][splash] - -[splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png - # OpenTelemetry Rust -The Rust [OpenTelemetry](https://opentelemetry.io/) implementation. +This crate contains the [OpenTelemetry](https://opentelemetry.io/) API for Rust. [![Crates.io: opentelemetry](https://img.shields.io/crates/v/opentelemetry.svg)](https://crates.io/crates/opentelemetry) [![Documentation](https://docs.rs/opentelemetry/badge.svg)](https://docs.rs/opentelemetry) @@ -15,11 +11,18 @@ The Rust [OpenTelemetry](https://opentelemetry.io/) implementation. ## Overview -OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument, -generate, collect, and export telemetry data (metrics, logs, and traces) for -analysis in order to understand your software's performance and behavior. You -can export and analyze them using [Prometheus], [Jaeger], and other -observability tools. +OpenTelemetry is an Observability framework and toolkit designed to create and +manage telemetry data such as traces, metrics, and logs. Crucially, +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. *Compiler support: [requires `rustc` 1.64+][msrv]* @@ -27,112 +30,34 @@ observability tools. [Jaeger]: https://www.jaegertracing.io [msrv]: #supported-rust-versions -## Getting Started - -```rust -use opentelemetry::{ - global, - sdk::trace::TracerProvider, - trace::{Tracer, TracerProvider as _}, -}; - -fn main() { - // Create a new trace pipeline that prints to stdout - let provider = TracerProvider::builder() - .with_simple_exporter(opentelemetry_stdout::SpanExporter::default()) - .build(); - let tracer = provider.tracer("readme_example"); - - tracer.in_span("doing_work", |cx| { - // Traced app logic here... - }); - - // Shutdown trace pipeline - global::shutdown_tracer_provider(); -} -``` - -See the [examples](../examples) directory for different integration patterns. - -## Ecosystem - -### Related Crates - -In addition to `opentelemetry`, which only carries the API, the -[`open-telemetry/opentelemetry-rust`] repository contains several additional -crates designed to be used with the `opentelemetry` ecosystem. This includes a -collection of trace `SpanExporter` and metrics pull and push controller -implementations, as well as utility and adapter crates to assist in propagating -state and instrumenting applications. - -In particular, the following crates are likely to be of interest: - -- [`opentelemetry-aws`] provides unofficial propagators for AWS X-ray. -- [`opentelemetry-contrib`] provides additional exporters and propagators that - are experimental. -- [`opentelemetry-datadog`] provides additional exporters to [`Datadog`]. -- [`opentelemetry-dynatrace`] *Deprecated, last release 0.4.0* provides additional exporters to [`Dynatrace`]. See [README][`opentelemetry-dynatrace-readme`] -- [`opentelemetry-http`] provides an interface for injecting and extracting - trace information from [`http`] headers. -- [`opentelemetry-jaeger`] provides a pipeline and exporter for sending trace - information to [`Jaeger`]. -- [`opentelemetry-otlp`] exporter for sending trace and metric data in the OTLP - format to the OpenTelemetry collector. -- [`opentelemetry-prometheus`] provides a pipeline and exporter for sending - metrics information to [`Prometheus`]. -- [`opentelemetry_sdk`] provides the standard reference implementation of - opentelemetry. -- [`opentelemetry-semantic-conventions`] provides standard names and semantic - otel conventions. -- [`opentelemetry-stackdriver`] provides an exporter for Google's [Cloud Trace] - (which used to be called StackDriver). -- [`opentelemetry-zipkin`] provides a pipeline and exporter for sending trace - information to [`Zipkin`]. - -Additionally, there are also several third-party crates which are not -maintained by the `opentelemetry` project. These include: - -- [`tracing-opentelemetry`] provides integration for applications instrumented - using the [`tracing`] API and ecosystem. -- [`actix-web-opentelemetry`] provides integration for the [`actix-web`] web - server and ecosystem. -- [`opentelemetry-application-insights`] provides an unofficial [Azure - Application Insights] exporter. -- [`opentelemetry-tide`] provides integration for the [`Tide`] web server and - ecosystem. - -If you're the maintainer of an `opentelemetry` ecosystem crate not listed -above, please let us know! We'd love to add your project to the list! - -[`open-telemetry/opentelemetry-rust`]: https://github.com/open-telemetry/opentelemetry-rust -[`opentelemetry-jaeger`]: https://crates.io/crates/opentelemetry-jaeger -[`Jaeger`]: https://www.jaegertracing.io -[`opentelemetry-otlp`]: https://crates.io/crates/opentelemetry-otlp -[`opentelemetry-http`]: https://crates.io/crates/opentelemetry-http -[`opentelemetry-prometheus`]: https://crates.io/crates/opentelemetry-prometheus -[`opentelemetry-aws`]: https://crates.io/crates/opentelemetry-aws -[`Prometheus`]: https://prometheus.io -[`opentelemetry-zipkin`]: https://crates.io/crates/opentelemetry-zipkin -[`Zipkin`]: https://zipkin.io -[`opentelemetry-contrib`]: https://crates.io/crates/opentelemetry-contrib -[`Datadog`]: https://www.datadoghq.com -[`Dynatrace`]: https://www.dynatrace.com -[`opentelemetry-datadog`]: https://crates.io/crates/opentelemetry-datadog -[`opentelemetry-dynatrace`]: https://crates.io/crates/opentelemetry-dynatrace -[`opentelemetry-dynatrace-readme`]: https://github.com/open-telemetry/opentelemetry-rust-contrib/blob/main/opentelemetry-dynatrace/README.md -[`opentelemetry-semantic-conventions`]: https://crates.io/crates/opentelemetry-semantic-conventions -[`http`]: https://crates.io/crates/http - -[`tracing-opentelemetry`]: https://crates.io/crates/tracing-opentelemetry -[`tracing`]: https://crates.io/crates/tracing -[`actix-web-opentelemetry`]: https://crates.io/crates/actix-web-opentelemetry -[`actix-web`]: https://crates.io/crates/actix-web -[`opentelemetry-application-insights`]: https://crates.io/crates/opentelemetry-application-insights -[Azure Application Insights]: https://docs.microsoft.com/en-us/azure/azure-monitor/app/app-insights-overview -[`opentelemetry-tide`]: https://crates.io/crates/opentelemetry-tide -[`Tide`]: https://crates.io/crates/tide -[`opentelemetry-stackdriver`]: https://crates.io/crates/opentelemetry-stackdriver -[Cloud Trace]: https://cloud.google.com/trace/ +### What does this crate contain? + +This is the API crate which contains the [Context +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md), +[Propagators +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md),[Baggage +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md), +[Logs Bridge +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md), +[Tracing +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md), +and [Metrics +API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md). + +This crates allows one to instrument libraries and application, but the APIs in +this crate are ["no-ops" or just +facades](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md#api-and-minimal-implementation), +with actual implementation occurring in the +[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk). This crate does +not deal with concepts such as processing or exporting of telemetry, they are +handled by the [opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk), +along with one or more exporters like the +[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). + +If you are a library author, then this is the crate you should be using to +instrument it. If you are familiar with `tracing` or `log` ecosystem, this crate +is just the facade part, and gets lights up, when the final application uses an +sdk implementation. ## Supported Rust Versions @@ -146,7 +71,3 @@ 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 - -See the [contributing file](../CONTRIBUTING.md). From 93667941ce2f7dd8dc349c9df0a0a25d87e80a03 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 27 Feb 2024 12:00:24 -0800 Subject: [PATCH 2/2] reformat and reword --- opentelemetry/README.md | 93 +++++++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 31 deletions(-) diff --git a/opentelemetry/README.md b/opentelemetry/README.md index 6b85245b89..f336a2f9b1 100644 --- a/opentelemetry/README.md +++ b/opentelemetry/README.md @@ -12,12 +12,12 @@ This crate contains the [OpenTelemetry](https://opentelemetry.io/) API for Rust. ## Overview OpenTelemetry is an Observability framework and toolkit designed to create and -manage telemetry data such as traces, metrics, and logs. Crucially, -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. +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 +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, @@ -32,32 +32,63 @@ of telemetry is intentionally left to other tools. ### What does this crate contain? -This is the API crate which contains the [Context -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md), -[Propagators -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/api-propagators.md),[Baggage -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md), -[Logs Bridge -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md), -[Tracing -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md), -and [Metrics -API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md). - -This crates allows one to instrument libraries and application, but the APIs in -this crate are ["no-ops" or just -facades](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md#api-and-minimal-implementation), -with actual implementation occurring in the -[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk). This crate does -not deal with concepts such as processing or exporting of telemetry, they are -handled by the [opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk), -along with one or more exporters like the -[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp). - -If you are a library author, then this is the crate you should be using to -instrument it. If you are familiar with `tracing` or `log` ecosystem, this crate -is just the facade part, and gets lights up, when the final application uses an -sdk implementation. +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/bridge-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. + +## Getting started + +See [docs](https://docs.rs/opentelemetry). ## Supported Rust Versions