From 32c51974793bd9c25b047755d0809c2911086952 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 17 Apr 2023 09:41:51 -0700 Subject: [PATCH 1/3] Add transition plan for upcoming breaking changes to the unstable HTTP semantic conventions --- CHANGELOG.md | 3 +++ .../metrics/semantic_conventions/http-metrics.md | 14 ++++++++++++++ specification/trace/semantic_conventions/http.md | 14 ++++++++++++++ 3 files changed, 31 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 52188613a7c..b7f6efffb3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,9 @@ release. ([#3388](https://github.com/open-telemetry/opentelemetry-specification/pull/3388)) - Change http.server.duration and http.client.duration units to seconds ([#3390](https://github.com/open-telemetry/opentelemetry-specification/pull/3390)) +- Add transition plan for upcoming breaking changes to the unstable HTTP semantic + conventions. + ([#3404](https://github.com/open-telemetry/opentelemetry-specification/pull/3404)) ### Compatibility diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 968b0575494..e1b9c59e0ff 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -26,6 +26,20 @@ operations. By adding HTTP attributes to metric events it allows for finely tune +> **Warning** +> v1.21.0 of this document will introduce significant breaking changes to the (not yet stable) +> HTTP semantic conventions. +> +> HTTP instrumentations updating from +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) +> (or prior) to this new version SHOULD bump their major version +> even though the instrumentation has not been declared stable. +> And the previous major version SHOULD be supported until February 1, 2024 +> (e.g. at least security patches). +> +> This major version bump will signal that users should take care when upgrading the +> instrumentation, including verifying whether their backend supports the new major version. + ## HTTP Server ### Metric: `http.server.duration` diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index dba45b01b57..26447a4cc1b 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -27,6 +27,20 @@ and various HTTP versions like 1.1, 2 and SPDY. +> **Warning** +> v1.21.0 of this document will introduce significant breaking changes to the (not yet stable) +> HTTP semantic conventions. +> +> HTTP instrumentations updating from +> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +> (or prior) to this new version SHOULD bump their major version +> even though the instrumentation has not been declared stable. +> And the previous major version SHOULD be supported until February 1, 2024 +> (e.g. at least security patches). +> +> This major version bump will signal that users should take care when upgrading the +> instrumentation, including verifying whether their backend supports the new major version. + ## Name HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). From f2c15d69c00889095eb480ba840ced8fc5eb1a3f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 18 Apr 2023 13:40:32 -0700 Subject: [PATCH 2/3] Add time period before stable release --- specification/metrics/semantic_conventions/http-metrics.md | 3 +++ specification/trace/semantic_conventions/http.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index e1b9c59e0ff..f19a6a8a93f 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -34,6 +34,9 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) > (or prior) to this new version SHOULD bump their major version > even though the instrumentation has not been declared stable. +> They SHOULD NOT release a stable version of that new major version until +> at least August 1, 2023 (this is to give backends some time to support the +> new changes). > And the previous major version SHOULD be supported until February 1, 2024 > (e.g. at least security patches). > diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 26447a4cc1b..0c82339ac27 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -35,6 +35,9 @@ and various HTTP versions like 1.1, 2 and SPDY. > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > (or prior) to this new version SHOULD bump their major version > even though the instrumentation has not been declared stable. +> They SHOULD NOT release a stable version of that new major version until +> at least August 1, 2023 (this is to give backends some time to support the +> new changes). > And the previous major version SHOULD be supported until February 1, 2024 > (e.g. at least security patches). > From bb8ac7d0b3e017b9505b87c8b669b6f1e70f4e46 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 24 Apr 2023 16:01:54 -0700 Subject: [PATCH 3/3] Two options --- .../metrics/semantic_conventions/http-metrics.md | 16 +++++++--------- specification/trace/semantic_conventions/http.md | 16 +++++++--------- 2 files changed, 14 insertions(+), 18 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index f19a6a8a93f..efe5fda957a 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -32,16 +32,14 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > > HTTP instrumentations updating from > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) -> (or prior) to this new version SHOULD bump their major version -> even though the instrumentation has not been declared stable. -> They SHOULD NOT release a stable version of that new major version until -> at least August 1, 2023 (this is to give backends some time to support the -> new changes). -> And the previous major version SHOULD be supported until February 1, 2024 -> (e.g. at least security patches). +> (or prior) to this new version SHOULD either: > -> This major version bump will signal that users should take care when upgrading the -> instrumentation, including verifying whether their backend supports the new major version. +> * wait to update until at least October 1, 2023, or +> * bump their major version and wait to release a stable version of the new major +> version until at least October 1, 2023. +> +> In both cases, the minor version prior to the update SHOULD be supported until +> February 1, 2024 (e.g. at least security patches). ## HTTP Server diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 0c82339ac27..4de980ceca5 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -33,16 +33,14 @@ and various HTTP versions like 1.1, 2 and SPDY. > > HTTP instrumentations updating from > [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) -> (or prior) to this new version SHOULD bump their major version -> even though the instrumentation has not been declared stable. -> They SHOULD NOT release a stable version of that new major version until -> at least August 1, 2023 (this is to give backends some time to support the -> new changes). -> And the previous major version SHOULD be supported until February 1, 2024 -> (e.g. at least security patches). +> (or prior) to this new version SHOULD either: > -> This major version bump will signal that users should take care when upgrading the -> instrumentation, including verifying whether their backend supports the new major version. +> * wait to update until at least October 1, 2023, or +> * bump their major version and wait to release a stable version of the new major +> version until at least October 1, 2023. +> +> In both cases, the minor version prior to the update SHOULD be supported until +> February 1, 2024 (e.g. at least security patches). ## Name