From e5acfc562d105a501fb0d285876f0cd5c759e3af Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 17 Jul 2025 02:28:44 +0000 Subject: [PATCH 1/3] Initial plan From 7da8d447a43abf865c0609fe47a22f11bed89ba1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 17 Jul 2025 02:39:02 +0000 Subject: [PATCH 2/3] Enhance README consistency across OpenTelemetry components Co-authored-by: cijothomas <5232798+cijothomas@users.noreply.github.com> --- opentelemetry-appender-log/README.md | 22 ++++++++++ opentelemetry-http/README.md | 43 ++++++++++++++++++-- opentelemetry-proto/README.md | 21 ++++++++-- opentelemetry-semantic-conventions/README.md | 4 ++ opentelemetry-stdout/README.md | 24 ++++++++--- 5 files changed, 101 insertions(+), 13 deletions(-) diff --git a/opentelemetry-appender-log/README.md b/opentelemetry-appender-log/README.md index b54cc181d3..a8c1e4a1ef 100644 --- a/opentelemetry-appender-log/README.md +++ b/opentelemetry-appender-log/README.md @@ -27,6 +27,28 @@ 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 + +## Getting started + +See [docs](https://docs.rs/opentelemetry-appender-log). + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-appender-log/CHANGELOG.md). + +## Supported Rust Versions + +OpenTelemetry is built against the latest stable release. The minimum supported +version is 1.75.0. 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. diff --git a/opentelemetry-http/README.md b/opentelemetry-http/README.md index 304553f1fc..229e2fbbed 100644 --- a/opentelemetry-http/README.md +++ b/opentelemetry-http/README.md @@ -4,9 +4,10 @@ [splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png -This crate contains helper implementations for sending HTTP requests. Uses -include propagating and extracting context over http, exporting telemetry, -requesting sampling strategies. +This crate contains helper implementations for sending HTTP requests with +[OpenTelemetry](https://opentelemetry.io/) integration. Uses include propagating +and extracting context over HTTP, exporting telemetry data, and requesting +sampling strategies. [![Crates.io: opentelemetry-http](https://img.shields.io/crates/v/opentelemetry-http.svg)](https://crates.io/crates/opentelemetry-http) [![Documentation](https://docs.rs/opentelemetry-http/badge.svg)](https://docs.rs/opentelemetry-http) @@ -14,7 +15,7 @@ requesting sampling strategies. [![GitHub Actions CI](https://github.com/open-telemetry/opentelemetry-rust/workflows/CI/badge.svg)](https://github.com/open-telemetry/opentelemetry-rust/actions?query=workflow%3ACI+branch%3Amain) [![Slack](https://img.shields.io/badge/slack-@cncf/otel/rust-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C03GDP0H023) -## OpenTelemetry Overview +## Overview OpenTelemetry is an Observability framework and toolkit designed to create and manage telemetry data such as traces, metrics, and logs. OpenTelemetry is @@ -31,6 +32,40 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* +[Prometheus]: https://prometheus.io +[Jaeger]: https://www.jaegertracing.io + +### What does this crate contain? + +This crate provides HTTP utilities and integrations for OpenTelemetry, +including: + +- **Context Propagation**: Helper implementations for propagating and extracting + OpenTelemetry context over HTTP headers, enabling distributed tracing across + service boundaries. +- **HTTP Client Support**: Integration with popular HTTP clients like `reqwest` + and `hyper` for automatic instrumentation and context propagation. +- **Exporter Utilities**: Common HTTP functionality used by exporters to send + telemetry data to collection endpoints. +- **Sampling Strategy Support**: Helper functions for requesting sampling + strategies from remote endpoints. + +This crate is typically used as a dependency by other OpenTelemetry components +rather than directly by end users, though it can be useful for custom +instrumentation scenarios. + +### Related crates + +This crate is commonly used alongside: + +- **[opentelemetry](https://crates.io/crates/opentelemetry):** The core OpenTelemetry API. +- **[opentelemetry-sdk](https://crates.io/crates/opentelemetry-sdk):** The OpenTelemetry SDK implementation. +- **[opentelemetry-otlp](https://crates.io/crates/opentelemetry-otlp):** OTLP exporter that uses this crate for HTTP transport. + +## Getting started + +See [docs](https://docs.rs/opentelemetry-http). + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-http/CHANGELOG.md). diff --git a/opentelemetry-proto/README.md b/opentelemetry-proto/README.md index 176d2a1412..3f63500545 100644 --- a/opentelemetry-proto/README.md +++ b/opentelemetry-proto/README.md @@ -1,13 +1,28 @@ +# OpenTelemetry Proto + ![OpenTelemetry — An observability framework for cloud-native software.][splash] [splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png -# OpenTelemetry Proto -This crate contains generated files from [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto) -repository and transformation between types from generated files and types defined in [opentelemetry](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry). +This crate contains generated Rust code from the +[opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto) +repository and provides transformation functions between the generated protobuf +types and the types defined in the +[opentelemetry](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry) +API crate. + +[![Crates.io: opentelemetry-proto](https://img.shields.io/crates/v/opentelemetry-proto.svg)](https://crates.io/crates/opentelemetry-proto) +[![Documentation](https://docs.rs/opentelemetry-proto/badge.svg)](https://docs.rs/opentelemetry-proto) +[![LICENSE](https://img.shields.io/crates/l/opentelemetry-proto)](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-proto/LICENSE) +[![GitHub Actions CI](https://github.com/open-telemetry/opentelemetry-rust/workflows/CI/badge.svg)](https://github.com/open-telemetry/opentelemetry-rust/actions?query=workflow%3ACI+branch%3Amain) +[![Slack](https://img.shields.io/badge/slack-@cncf/otel/rust-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/archives/C03GDP0H023) *[Supported Rust Versions](#supported-rust-versions)* +## Getting started + +See [docs](https://docs.rs/opentelemetry-proto). + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-proto/CHANGELOG.md). diff --git a/opentelemetry-semantic-conventions/README.md b/opentelemetry-semantic-conventions/README.md index 105eb5e455..c24a42d763 100644 --- a/opentelemetry-semantic-conventions/README.md +++ b/opentelemetry-semantic-conventions/README.md @@ -25,6 +25,10 @@ and visualization tools. *[Supported Rust Versions](#supported-rust-versions)* +## Getting started + +See [docs](https://docs.rs/opentelemetry-semantic-conventions). + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-semantic-conventions/CHANGELOG.md). diff --git a/opentelemetry-stdout/README.md b/opentelemetry-stdout/README.md index c4414aef5a..83f4625268 100644 --- a/opentelemetry-stdout/README.md +++ b/opentelemetry-stdout/README.md @@ -5,7 +5,10 @@ [splash]: https://raw.githubusercontent.com/open-telemetry/opentelemetry-rust/main/assets/logo-text.png This crate contains an [OpenTelemetry](https://opentelemetry.io/) exporter that -prints telemetry (logs, metrics and traces) to the standard output. +outputs telemetry data (logs, metrics, and traces) to standard output in a +human-readable format. It is designed for educational purposes, debugging, and +development workflows where you want to quickly inspect telemetry data without +setting up external observability infrastructure. [![Crates.io: opentelemetry-stdout](https://img.shields.io/crates/v/opentelemetry-stdout.svg)](https://crates.io/crates/opentelemetry-stdout) [![Documentation](https://docs.rs/opentelemetry-stdout/badge.svg)](https://docs.rs/opentelemetry-stdout) @@ -36,11 +39,20 @@ of telemetry is intentionally left to other tools. ### What does this crate contain? -This crate includes exporters that support all three signals - Logs, Metrics, -and Traces — to standard output. It is intended solely for educational and -debugging purposes. Please note, this crate is not optimized for performance, -and the format of the output may change, making it unsuitable for production -environments +This crate provides exporters that support all three OpenTelemetry signals: + +- **Trace Exporter**: Outputs distributed tracing data showing request flows + and timing information across services. +- **Metrics Exporter**: Outputs measurement data such as counters, gauges, and + histograms for monitoring application performance. +- **Logs Exporter**: Outputs structured log data with OpenTelemetry context + information. + +All exporters format the telemetry data in a human-readable way and write it to +standard output. This crate is intended solely for educational and debugging +purposes. Please note, this crate is not optimized for performance, and the +format of the output may change, making it unsuitable for production +environments. ## Getting started From 6f990f5ba320a4a12adef08ae773e7a10802ceb2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 17 Jul 2025 02:47:45 +0000 Subject: [PATCH 3/3] Update README consistency for remaining OpenTelemetry crates Co-authored-by: cijothomas <5232798+cijothomas@users.noreply.github.com> --- opentelemetry-appender-tracing/README.md | 14 +++++++++++ opentelemetry-jaeger-propagator/README.md | 15 ++++++++++++ opentelemetry-otlp/README.md | 14 +++++++++++ opentelemetry-prometheus/README.md | 30 +++++++++++++++++++++++ opentelemetry-zipkin/README.md | 15 +++++++++++- 5 files changed, 87 insertions(+), 1 deletion(-) diff --git a/opentelemetry-appender-tracing/README.md b/opentelemetry-appender-tracing/README.md index b5aa3305dc..0484278dfb 100644 --- a/opentelemetry-appender-tracing/README.md +++ b/opentelemetry-appender-tracing/README.md @@ -35,6 +35,20 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* +### What does this crate contain? + +This crate provides a bridge for integrating the [tracing crate](https://tracing.rs/) with OpenTelemetry's logging pipeline. It includes: + +- **Log Appender**: A component that captures log events from tracing and forwards them to OpenTelemetry's logging system +- **Event Bridge**: Converts tracing events into OpenTelemetry log records while preserving metadata and context +- **Integration Support**: Seamless integration with existing tracing-based applications to enable OpenTelemetry log collection + +This appender is specifically designed for scenarios where you want to collect logs through OpenTelemetry while using the tracing crate for instrumentation. + +## Getting started + +See the [docs](https://docs.rs/opentelemetry-appender-tracing) for detailed examples and API reference. + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-appender-tracing/CHANGELOG.md). diff --git a/opentelemetry-jaeger-propagator/README.md b/opentelemetry-jaeger-propagator/README.md index ec4c68d392..0e20e62e39 100644 --- a/opentelemetry-jaeger-propagator/README.md +++ b/opentelemetry-jaeger-propagator/README.md @@ -31,6 +31,21 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* +### What does this crate contain? + +This crate provides Jaeger-specific context propagation for OpenTelemetry applications. It includes: + +- **Jaeger Propagator**: Implementation of Jaeger's text map propagation format for distributed tracing +- **Context Extraction**: Ability to extract Jaeger trace context from HTTP headers and other carriers +- **Context Injection**: Functionality to inject OpenTelemetry trace context into Jaeger format for downstream services +- **Legacy Compatibility**: Support for applications that need to interoperate with existing Jaeger-instrumented services + +Note: This crate is specifically for context propagation. To export telemetry data to Jaeger, use the `opentelemetry-otlp` crate. + +## Getting started + +See the [docs](https://docs.rs/opentelemetry-jaeger-propagator) for detailed examples and API reference. + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-jaeger-propagator/CHANGELOG.md). diff --git a/opentelemetry-otlp/README.md b/opentelemetry-otlp/README.md index 6592d0467b..ccc5009b6f 100644 --- a/opentelemetry-otlp/README.md +++ b/opentelemetry-otlp/README.md @@ -35,6 +35,20 @@ of telemetry is intentionally left to other tools. [Prometheus]: https://prometheus.io [Jaeger]: https://www.jaegertracing.io +### What does this crate contain? + +This crate provides OTLP (OpenTelemetry Protocol) exporter implementations for sending telemetry data to OTLP-compatible backends. It includes: + +- **Trace Exporter**: Export distributed tracing data in OTLP format +- **Metrics Exporter**: Export metrics data to OTLP endpoints +- **Logs Exporter**: Export log data using the OTLP protocol +- **HTTP Transport**: Send telemetry over HTTP/1.1 and HTTP/2 with configurable compression +- **gRPC Transport**: Send telemetry using gRPC protocol for high-performance scenarios +- **Authentication Support**: Built-in support for various authentication mechanisms (headers, mTLS, etc.) +- **Batch Processing**: Efficient batching and retry mechanisms for reliable telemetry delivery + +The OTLP format is the recommended way to export telemetry as it's vendor-neutral and supported by many observability backends including Jaeger, Prometheus, and commercial vendors. + ## Getting started See [docs](https://docs.rs/opentelemetry-otlp). diff --git a/opentelemetry-prometheus/README.md b/opentelemetry-prometheus/README.md index 6b35843814..9326ec7248 100644 --- a/opentelemetry-prometheus/README.md +++ b/opentelemetry-prometheus/README.md @@ -44,6 +44,36 @@ of telemetry is intentionally left to other tools. [`Prometheus`]: https://prometheus.io [`OpenTelemetry`]: https://crates.io/crates/opentelemetry +### What does this crate contain? + +**⚠️ This crate is deprecated and no longer recommended for use.** + +This crate previously provided direct Prometheus metrics export functionality, but has been discontinued due to: +- Dependency on unmaintained `protobuf` crate +- Unresolved security vulnerabilities +- Limited maintenance resources + +For new projects, use the [OTLP exporter](https://docs.rs/opentelemetry-otlp/) instead, as Prometheus now natively supports OTLP. + +## Getting started + +**For new projects:** Use the [opentelemetry-otlp](https://docs.rs/opentelemetry-otlp/) crate instead. See the [Prometheus OTLP documentation](https://prometheus.io/docs/guides/opentelemetry/#enable-the-otlp-receiver) for integration details. + +**For existing projects:** See the [docs](https://docs.rs/opentelemetry-prometheus) for legacy API reference, but plan migration to OTLP. + ## Release Notes You can find the release notes (changelog) [here](https://github.com/open-telemetry/opentelemetry-rust/blob/main/opentelemetry-prometheus/CHANGELOG.md). + +## Supported Rust Versions + +OpenTelemetry is built against the latest stable release. The minimum supported +version is 1.75.0. 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. diff --git a/opentelemetry-zipkin/README.md b/opentelemetry-zipkin/README.md index 667d11815c..07c7d37a88 100644 --- a/opentelemetry-zipkin/README.md +++ b/opentelemetry-zipkin/README.md @@ -32,7 +32,20 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* -## Quickstart +### What does this crate contain? + +This crate provides a Zipkin exporter for OpenTelemetry trace data. It includes: + +- **Zipkin Exporter**: Export OpenTelemetry traces to Zipkin-compatible backends +- **HTTP Transport**: Send trace data via HTTP/JSON to Zipkin endpoints +- **Span Conversion**: Convert OpenTelemetry spans to Zipkin's data model while preserving trace relationships +- **Batch Processing**: Efficient batching of spans for optimized network usage +- **HTTP Client Flexibility**: Support for multiple HTTP client implementations (reqwest, surf, etc.) +- **Async Support**: Full async/await compatibility for non-blocking telemetry export + +Note: This exporter only supports traces. For metrics and logs, use the OTLP exporter or other appropriate exporters. + +## Getting started First make sure you have a running version of the zipkin process you want to send data to: