From 10455a15a3f9e5300bb7c3f7469d9a84fe4f2c08 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Wed, 19 Mar 2025 17:31:13 -0700 Subject: [PATCH 1/7] chore: Prepare docs before 0.29 --- README.md | 6 +-- docs/migration_0.29.md | 86 ++++++++++++++++++++++++++++++++++++++ opentelemetry/CHANGELOG.md | 1 - 3 files changed, 89 insertions(+), 4 deletions(-) create mode 100644 docs/migration_0.29.md diff --git a/README.md b/README.md index 3cf294cb69..c48f77a663 100644 --- a/README.md +++ b/README.md @@ -31,12 +31,12 @@ documentation. | Signal/Component | Overall Status | | -------------------- | ------------------ | | Context | Beta | -| Baggage | Beta | +| Baggage | RC | | Propagators | Beta | | Logs-API | Stable* | -| Logs-SDK | RC | +| Logs-SDK | Stable | | Logs-OTLP Exporter | RC | -| Logs-Appender-Tracing | RC | +| Logs-Appender-Tracing | Stable | | Metrics-API | Stable | | Metrics-SDK | RC | | Metrics-OTLP Exporter | RC | diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md new file mode 100644 index 0000000000..194b094cb6 --- /dev/null +++ b/docs/migration_0.29.md @@ -0,0 +1,86 @@ +# Migration Guide from 0.28 to 0.29 + +OpenTelemetry Rust 0.29 introduces few breaking changes. This guide aims to +facilitate a smooth migration for common use cases involving the +`opentelemetry`, `opentelemetry_sdk`, `opentelemetry-otlp`, and +`opentelemetry-appender-tracing` crates. For a comprehensive list of changes, +please refer to the detailed changelog for each crate. This document covers only +the most common scenarios. Note that changes that only affect +custom exporter/processor authors are not mentioned in this doc. + +OpenTelemetry Metrics API, Log-Bridge API were declared stable in 0.28, +and has no breaking changes. + +## Baggage Changes + +The Baggage API has been redesigned to align with the OpenTelemetry +specification. While the core API for interacting with Baggage remains the same, +the accepted data types have changed. Baggage Keys now only allow strings (ASCII +visual characters), and Baggage values are restricted to strings. + +For detailed changes, see the [changelog](../opentelemetry/CHANGELOG.md). With +version 0.29, the Baggage API has reached "Release Candidate" status, meaning +further breaking changes will be highly restricted. + +## Appender-Tracing Changes + +The `opentelemetry-appender-tracing` crate, which bridges `tracing` events to +OpenTelemetry logs, has been updated to properly map `tracing` data types to the +OpenTelemetry model. As of version 0.29, this crate is considered "Stable," and +no further breaking changes will be made without a major version bump. + +## Configuration via Environment Variables + +The 0.29 release aligns OpenTelemetry Rust with the rest of the OpenTelemetry +ecosystem by treating any code-based configuration as final (i.e., it cannot be +overridden by environment variables). This policy was partially true before but +is now applied consistently. If you prefer to configure your application via +environment variables, avoid configuring it programmatically. + +## Discontinuing Dedicated Prometheus Exporter + +The `opentelemetry-prometheus` crate will be discontinued with the 0.29 release. +Active development on this crate ceased a few months ago. Given that Prometheus +now natively supports OTLP, and considering that the OpenTelemetry Rust project +is still working towards a 1.0 release, we need to focus on essential components +to maintain scope and ensure timely delivery. + +Prometheus interoperability remains a key goal for OpenTelemetry. However, the +current `opentelemetry-prometheus` crate requires a major rewrite to eliminate +dependencies on unmaintained crates. We may reintroduce a dedicated Prometheus +exporter in the future once these issues are resolved. + +For those using Prometheus as a backend, you can integrate with Prometheus using +the following methods: + +1. Use the OTLP Exporter to push metrics directly to Prometheus. +2. If you require a pull (scrape) model, push metrics to an OpenTelemetry + Collector using the OTLP Exporter, and configure Prometheus to scrape the + OpenTelemetry Collector. + +These alternatives ensure continued Prometheus integration while allowing us to +focus on achieving a stable 1.0 release for OpenTelemetry Rust. + +## Next Release + +In the next release, we expect to stabilize the Metrics SDK and resolve the +long-standing question of `tokio-tracing` vs. `opentelemetry tracing`. + +## Instrumentation Libraries + +Unlike other OpenTelemetry language implementations, OpenTelemetry Rust did not +maintain any instrumentations on its own. This has recently changed with a +[contribution](https://github.com/open-telemetry/opentelemetry-rust-contrib/pull/202) +from one of the founding members of the OpenTelemetry Rust project to the +contrib repo, providing an instrumentation library for +[`actix-web`](https://github.com/open-telemetry/opentelemetry-rust-contrib/tree/main/actix-web-opentelemetry). +We expect this instrumentation to eventually showcase best practices for +instrumentation. + +We welcome more contributions for instrumentations to the contrib repo. + +## Thanks + +Thanks to everyone who helped with this milestone. Please share your feedback +via GitHub issues or the OTel-Rust Slack channel +[here](https://cloud-native.slack.com/archives/C03GDP0H023). diff --git a/opentelemetry/CHANGELOG.md b/opentelemetry/CHANGELOG.md index 00ab0be983..a193ee9cfa 100644 --- a/opentelemetry/CHANGELOG.md +++ b/opentelemetry/CHANGELOG.md @@ -5,7 +5,6 @@ - *Breaking* Moved `ExportError` trait from `opentelemetry::trace::ExportError` to `opentelemetry_sdk::export::ExportError` - *Breaking* Moved `TraceError` enum from `opentelemetry::trace::TraceError` to `opentelemetry_sdk::trace::TraceError` - *Breaking* Moved `TraceResult` type alias from `opentelemetry::trace::TraceResult` to `opentelemetry_sdk::trace::TraceResult` -- {PLACEHOLDER} - Remove the above completely. // TODO fill this when changes are actually in. - Bug Fix: `InstrumentationScope` implementation for `PartialEq` and `Hash` fixed to include Attributes also. - **Breaking changes for baggage users**: [#2717](https://github.com/open-telemetry/opentelemetry-rust/issues/2717) - Changed value type of `Baggage` from `Value` to `StringValue` From a8445ed928e4377b42df39c7769a07535d4b491d Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Thu, 20 Mar 2025 16:11:16 -0700 Subject: [PATCH 2/7] nit rewording --- docs/migration_0.29.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md index 194b094cb6..d3adf2b334 100644 --- a/docs/migration_0.29.md +++ b/docs/migration_0.29.md @@ -5,11 +5,11 @@ facilitate a smooth migration for common use cases involving the `opentelemetry`, `opentelemetry_sdk`, `opentelemetry-otlp`, and `opentelemetry-appender-tracing` crates. For a comprehensive list of changes, please refer to the detailed changelog for each crate. This document covers only -the most common scenarios. Note that changes that only affect -custom exporter/processor authors are not mentioned in this doc. +the most common scenarios. Note that changes that only affect custom +exporter/processor authors are not mentioned in this doc. -OpenTelemetry Metrics API, Log-Bridge API were declared stable in 0.28, -and has no breaking changes. +OpenTelemetry Metrics API, Log-Bridge API were declared stable in 0.28, and has +no breaking changes. ## Baggage Changes @@ -50,6 +50,8 @@ current `opentelemetry-prometheus` crate requires a major rewrite to eliminate dependencies on unmaintained crates. We may reintroduce a dedicated Prometheus exporter in the future once these issues are resolved. +### Migration guide + For those using Prometheus as a backend, you can integrate with Prometheus using the following methods: From 626807504a8ff80d13e05d6cf7406631fae6ce4d Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Fri, 21 Mar 2025 05:50:22 -0700 Subject: [PATCH 3/7] next release tweaks --- docs/migration_0.29.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md index d3adf2b334..f9abf70bdf 100644 --- a/docs/migration_0.29.md +++ b/docs/migration_0.29.md @@ -65,8 +65,12 @@ focus on achieving a stable 1.0 release for OpenTelemetry Rust. ## Next Release -In the next release, we expect to stabilize the Metrics SDK and resolve the -long-standing question of `tokio-tracing` vs. `opentelemetry tracing`. +In the [next +release](https://github.com/open-telemetry/opentelemetry-rust/milestone/21), we +expect to stabilize the Metrics SDK and resolve the long-standing question of +`tokio-tracing` vs. `opentelemetry tracing`, which is an pre-req before +stabilizing Distributed Tracing. Additionally `Context` is also expected to be +enhanced with the ability to suppress telemetry-induced-telemetry. ## Instrumentation Libraries From 129cb8f6a20756c765081262231841c60a0390ef Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Fri, 21 Mar 2025 09:48:37 -0700 Subject: [PATCH 4/7] Update docs/migration_0.29.md Co-authored-by: Utkarsh Umesan Pillai <66651184+utpilla@users.noreply.github.com> --- docs/migration_0.29.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md index f9abf70bdf..6b4e7b72a7 100644 --- a/docs/migration_0.29.md +++ b/docs/migration_0.29.md @@ -1,6 +1,6 @@ # Migration Guide from 0.28 to 0.29 -OpenTelemetry Rust 0.29 introduces few breaking changes. This guide aims to +OpenTelemetry Rust 0.29 introduces a few breaking changes. This guide aims to facilitate a smooth migration for common use cases involving the `opentelemetry`, `opentelemetry_sdk`, `opentelemetry-otlp`, and `opentelemetry-appender-tracing` crates. For a comprehensive list of changes, From a3fd6155fd8324f35c4da43defe9857833bf4e95 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Fri, 21 Mar 2025 11:32:24 -0700 Subject: [PATCH 5/7] review feedback --- docs/migration_0.29.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md index 6b4e7b72a7..5586b42eb8 100644 --- a/docs/migration_0.29.md +++ b/docs/migration_0.29.md @@ -8,7 +8,7 @@ please refer to the detailed changelog for each crate. This document covers only the most common scenarios. Note that changes that only affect custom exporter/processor authors are not mentioned in this doc. -OpenTelemetry Metrics API, Log-Bridge API were declared stable in 0.28, and has +OpenTelemetry Metrics API and Log-Bridge API were declared stable in 0.28, and have no breaking changes. ## Baggage Changes @@ -16,7 +16,7 @@ no breaking changes. The Baggage API has been redesigned to align with the OpenTelemetry specification. While the core API for interacting with Baggage remains the same, the accepted data types have changed. Baggage Keys now only allow strings (ASCII -visual characters), and Baggage values are restricted to strings. +printable characters), and Baggage values are restricted to strings. For detailed changes, see the [changelog](../opentelemetry/CHANGELOG.md). With version 0.29, the Baggage API has reached "Release Candidate" status, meaning @@ -50,7 +50,7 @@ current `opentelemetry-prometheus` crate requires a major rewrite to eliminate dependencies on unmaintained crates. We may reintroduce a dedicated Prometheus exporter in the future once these issues are resolved. -### Migration guide +### Migration Guide For those using Prometheus as a backend, you can integrate with Prometheus using the following methods: @@ -68,8 +68,8 @@ focus on achieving a stable 1.0 release for OpenTelemetry Rust. In the [next release](https://github.com/open-telemetry/opentelemetry-rust/milestone/21), we expect to stabilize the Metrics SDK and resolve the long-standing question of -`tokio-tracing` vs. `opentelemetry tracing`, which is an pre-req before -stabilizing Distributed Tracing. Additionally `Context` is also expected to be +`tokio-tracing` vs. `opentelemetry tracing`, which is an prerequisite before +stabilizing Distributed Tracing. Additionally, `Context` is also expected to be enhanced with the ability to suppress telemetry-induced-telemetry. ## Instrumentation Libraries From 4dcfc5d6ece25fba113bc5732f1fe41dd4fe9cd9 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Fri, 21 Mar 2025 11:35:29 -0700 Subject: [PATCH 6/7] typos --- docs/migration_0.29.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md index 5586b42eb8..f8c28cff2e 100644 --- a/docs/migration_0.29.md +++ b/docs/migration_0.29.md @@ -68,7 +68,7 @@ focus on achieving a stable 1.0 release for OpenTelemetry Rust. In the [next release](https://github.com/open-telemetry/opentelemetry-rust/milestone/21), we expect to stabilize the Metrics SDK and resolve the long-standing question of -`tokio-tracing` vs. `opentelemetry tracing`, which is an prerequisite before +`tokio-tracing` vs. `opentelemetry tracing`, which is a prerequisite before stabilizing Distributed Tracing. Additionally, `Context` is also expected to be enhanced with the ability to suppress telemetry-induced-telemetry. From f5e6b8fa7ebc1fd8df804568d0cdc1836683ad6a Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Fri, 21 Mar 2025 11:36:39 -0700 Subject: [PATCH 7/7] slight rearrangement --- docs/migration_0.29.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/migration_0.29.md b/docs/migration_0.29.md index f8c28cff2e..28a3ccab34 100644 --- a/docs/migration_0.29.md +++ b/docs/migration_0.29.md @@ -74,19 +74,19 @@ enhanced with the ability to suppress telemetry-induced-telemetry. ## Instrumentation Libraries -Unlike other OpenTelemetry language implementations, OpenTelemetry Rust did not -maintain any instrumentations on its own. This has recently changed with a +Unlike other OpenTelemetry language implementations, OpenTelemetry Rust historically did not +maintain any instrumentations directly. This has recently changed with a [contribution](https://github.com/open-telemetry/opentelemetry-rust-contrib/pull/202) from one of the founding members of the OpenTelemetry Rust project to the -contrib repo, providing an instrumentation library for +contrib repository, providing an instrumentation library for [`actix-web`](https://github.com/open-telemetry/opentelemetry-rust-contrib/tree/main/actix-web-opentelemetry). -We expect this instrumentation to eventually showcase best practices for -instrumentation. +We expect that this instrumentation will serve as a reference implementation demonstrating best practices for +creating OpenTelemetry instrumentations in Rust. -We welcome more contributions for instrumentations to the contrib repo. +We welcome additional contributions of instrumentation libraries to the contrib repository. ## Thanks -Thanks to everyone who helped with this milestone. Please share your feedback -via GitHub issues or the OTel-Rust Slack channel +Thank you to everyone who contributed to this milestone. Please share your feedback +through GitHub issues or join the discussion in the OTel-Rust Slack channel [here](https://cloud-native.slack.com/archives/C03GDP0H023).