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).