From 03f679404cdaff8c48b43be46c1c18c78cca6212 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Thu, 6 Feb 2025 12:09:40 -0800 Subject: [PATCH] Readme updates in prep for release --- README.md | 66 +++++++------------- opentelemetry-appender-log/README.md | 4 ++ opentelemetry-appender-tracing/README.md | 4 ++ opentelemetry-http/README.md | 4 ++ opentelemetry-jaeger-propagator/README.md | 4 ++ opentelemetry-otlp/README.md | 4 ++ opentelemetry-prometheus/README.md | 4 ++ opentelemetry-proto/README.md | 4 ++ opentelemetry-sdk/README.md | 4 ++ opentelemetry-semantic-conventions/README.md | 4 ++ opentelemetry-stdout/README.md | 4 ++ opentelemetry-zipkin/README.md | 4 ++ opentelemetry/README.md | 5 +- 13 files changed, 70 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index fbd0fe8c56..4f90f9c014 100644 --- a/README.md +++ b/README.md @@ -30,13 +30,13 @@ documentation. | Signal/Component | Overall Status | | -------------------- | ------------------ | -| Logs-API | RC* | -| Logs-SDK | Beta | -| Logs-OTLP Exporter | Beta | -| Logs-Appender-Tracing | Beta | -| Metrics-API | RC | -| Metrics-SDK | Beta | -| Metrics-OTLP Exporter | Beta | +| Logs-API | Stable* | +| Logs-SDK | RC | +| Logs-OTLP Exporter | RC | +| Logs-Appender-Tracing | RC | +| Metrics-API | Stable | +| Metrics-SDK | RC | +| Metrics-OTLP Exporter | RC | | Traces-API | Beta | | Traces-SDK | Beta | | Traces-OTLP Exporter | Beta | @@ -55,50 +55,28 @@ If you already use the logging APIs from above, continue to use them, and use the appenders above to bridge the logs to OpenTelemetry. If you are using a library not listed here, feel free to contribute a new appender for the same. -If you are starting fresh, then consider using +If you are starting fresh, we recommend using [tracing](https://github.com/tokio-rs/tracing) as your logging API. It supports -structured logging and is actively maintained. +structured logging and is actively maintained. `OpenTelemetry` itself uses +`tracing` for its internal logging. Project versioning information and stability guarantees can be found [here](VERSIONING.md). ## Getting Started -```rust -use opentelemetry::trace::{ - TraceContextExt, - Tracer, - TracerProvider, -}; -use opentelemetry_sdk::trace::SdkTracerProvider; - -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 - provider.shutdown().expect("TracerProvider should shutdown successfully") -} -``` - -The example above requires the following packages: - -```toml -# Cargo.toml -[dependencies] -opentelemetry = "0.27" -opentelemetry_sdk = "0.27" -opentelemetry-stdout = { version = "0.27", features = ["trace"] } -``` - -See the [examples](./examples) directory for different integration patterns. +If you are new to OpenTelemetry, start with the [Stdout +Example](./opentelemetry-stdout/examples/basic.rs). This example demonstrates +how to use OpenTelemetry for logs, metrics, and traces, and display +telemetry data on your console. + +For those using OTLP, the recommended OpenTelemetry Exporter for production +scenarios, refer to the [OTLP Example - +HTTP](./opentelemetry-otlp/examples/basic-otlp-http/README.md) and the [OTLP +Example - gRPC](./opentelemetry-otlp/examples/basic-otlp/README.md). + +Additional examples for various integration patterns can be found in the +[examples](./examples) directory. ## Overview of crates diff --git a/opentelemetry-appender-log/README.md b/opentelemetry-appender-log/README.md index 455ecf1100..5b31e53641 100644 --- a/opentelemetry-appender-log/README.md +++ b/opentelemetry-appender-log/README.md @@ -26,3 +26,7 @@ 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. + +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). diff --git a/opentelemetry-appender-tracing/README.md b/opentelemetry-appender-tracing/README.md index 7f4a35b214..636a57225f 100644 --- a/opentelemetry-appender-tracing/README.md +++ b/opentelemetry-appender-tracing/README.md @@ -35,6 +35,10 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-http/README.md b/opentelemetry-http/README.md index 58f82210ab..671efc2e88 100644 --- a/opentelemetry-http/README.md +++ b/opentelemetry-http/README.md @@ -31,6 +31,10 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-jaeger-propagator/README.md b/opentelemetry-jaeger-propagator/README.md index 5955df7fc0..e314e5fc08 100644 --- a/opentelemetry-jaeger-propagator/README.md +++ b/opentelemetry-jaeger-propagator/README.md @@ -31,6 +31,10 @@ of telemetry is intentionally left to other tools. *[Supported Rust Versions](#supported-rust-versions)* +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-otlp/README.md b/opentelemetry-otlp/README.md index 16a54c875b..0da057bce4 100644 --- a/opentelemetry-otlp/README.md +++ b/opentelemetry-otlp/README.md @@ -39,6 +39,10 @@ of telemetry is intentionally left to other tools. See [docs](https://docs.rs/opentelemetry-otlp). +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-prometheus/README.md b/opentelemetry-prometheus/README.md index 35142e9193..87fa04f188 100644 --- a/opentelemetry-prometheus/README.md +++ b/opentelemetry-prometheus/README.md @@ -32,3 +32,7 @@ of telemetry is intentionally left to other tools. [`Prometheus`]: https://prometheus.io [`OpenTelemetry`]: https://crates.io/crates/opentelemetry + +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). diff --git a/opentelemetry-proto/README.md b/opentelemetry-proto/README.md index 8c82384779..37dcedabea 100644 --- a/opentelemetry-proto/README.md +++ b/opentelemetry-proto/README.md @@ -8,6 +8,10 @@ repository and transformation between types from generated files and types defin *[Supported Rust Versions](#supported-rust-versions)* +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-sdk/README.md b/opentelemetry-sdk/README.md index bbbd4c20a0..ab70d71621 100644 --- a/opentelemetry-sdk/README.md +++ b/opentelemetry-sdk/README.md @@ -100,6 +100,10 @@ additional exporters and other related components as well. See [docs](https://docs.rs/opentelemetry-sdk). +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-semantic-conventions/README.md b/opentelemetry-semantic-conventions/README.md index 2d3459fe28..4e61e9796f 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)* +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-stdout/README.md b/opentelemetry-stdout/README.md index 6e2f1f4185..f842ee7fa5 100644 --- a/opentelemetry-stdout/README.md +++ b/opentelemetry-stdout/README.md @@ -46,6 +46,10 @@ environments See [docs](https://docs.rs/opentelemetry-stdout). +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry-zipkin/README.md b/opentelemetry-zipkin/README.md index 2220e90cd0..ff0b5518aa 100644 --- a/opentelemetry-zipkin/README.md +++ b/opentelemetry-zipkin/README.md @@ -107,6 +107,10 @@ available so be sure to match them appropriately. [`ZipkinPipelineBuilder`]: https://docs.rs/opentelemetry-zipkin/latest/opentelemetry_zipkin/struct.ZipkinPipelineBuilder.html +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported diff --git a/opentelemetry/README.md b/opentelemetry/README.md index 522c91e632..edb5956502 100644 --- a/opentelemetry/README.md +++ b/opentelemetry/README.md @@ -32,7 +32,6 @@ of telemetry is intentionally left to other tools. [Prometheus]: https://prometheus.io [Jaeger]: https://www.jaegertracing.io -[msrv]: #supported-rust-versions ### What does this crate contain? @@ -130,6 +129,10 @@ additional exporters and other related components as well. See [docs](https://docs.rs/opentelemetry). +## Release Notes + +You can find the release notes (changelog) [here](./CHANGELOG.md). + ## Supported Rust Versions OpenTelemetry is built against the latest stable release. The minimum supported