From dfc9d266911c296f09cc9342cde2485c0b5e5343 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 11 Apr 2023 11:56:57 -0700 Subject: [PATCH 1/3] Add transition plan for upcoming breaking changes to the unstable HTTP semantic conventions --- CHANGELOG.md | 4 ++++ .../metrics/semantic_conventions/http-metrics.md | 14 ++++++++++++++ specification/trace/semantic_conventions/http.md | 14 ++++++++++++++ 3 files changed, 32 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4921c3137ad..acd09b0e73c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,10 @@ release. ### Semantic Conventions +- Add transition plan for upcoming breaking changes to the unstable HTTP semantic + conventions. + ([#3381](https://github.com/open-telemetry/opentelemetry-specification/pull/3381)) + ### Compatibility ### OpenTelemetry Protocol diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index e18bb475bae..1598fde4e75 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** +> HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than +> [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) +> until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions +> during this time is ok). +> +> After October 1, 2023, HTTP instrumentation published from +> [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) +> which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where +> they support both the old (1.20.0 or earlier) and the latest HTTP semantic conventions. +> This support can be provided by a configuration option on the latest instrumentation version +> to opt-in (revert) to the old conventions, or it can be provided by patching old +> instrumentation versions for security-related issues during this overlap. + ## HTTP Server ### Metric: `http.server.duration` diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 636683beeb0..825e039f490 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** +> HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than +> [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) +> until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions +> during this time is ok). +> +> After October 1, 2023, HTTP instrumentation published from +> [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) +> which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where +> they support both the old (1.20.0 or earlier) and the latest HTTP semantic conventions. +> This support can be provided by a configuration option on the latest instrumentation version +> to opt-in (revert) to the old conventions, or it can be provided by patching old +> instrumentation versions for security-related issues during this overlap. + ## Name HTTP spans MUST follow the overall [guidelines for span names](../api.md#span). From f8639a2cdcf24f14e6b67aa35b1542ff6e10e793 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 11 Apr 2023 15:03:33 -0700 Subject: [PATCH 2/3] clarifications --- .../metrics/semantic_conventions/http-metrics.md | 14 +++++++------- specification/trace/semantic_conventions/http.md | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 1598fde4e75..e6dd7ffec6d 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -30,15 +30,15 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than > [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) > until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions -> during this time is ok). +> during this time is ok). The purpose of this time period is to give vendors time +> to support the new conventions. > -> After October 1, 2023, HTTP instrumentation published from +> After October 1, 2023, whenever an HTTP instrumentation published from > [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) -> which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where -> they support both the old (1.20.0 or earlier) and the latest HTTP semantic conventions. -> This support can be provided by a configuration option on the latest instrumentation version -> to opt-in (revert) to the old conventions, or it can be provided by patching old -> instrumentation versions for security-related issues during this overlap. +> adopts the latest HTTP semantic conventions, the prior version SHOULD still be +> supported (e.g. security patches) for 3-months (an opt-out flag on the latest +> instrumentation to emit the prior HTTP semantic conventions during this time is ok). +> The purpose of this time period is to give users time to migrate. ## HTTP Server diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 825e039f490..e4d95789e39 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -31,15 +31,15 @@ and various HTTP versions like 1.1, 2 and SPDY. > HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than > [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) > until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions -> during this time is ok). +> during this time is ok). The purpose of this time period is to give vendors time +> to support the new conventions. > -> After October 1, 2023, HTTP instrumentation published from +> After October 1, 2023, whenever an HTTP instrumentation published from > [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) -> which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where -> they support both the old (1.20.0 or earlier) and the latest HTTP semantic conventions. -> This support can be provided by a configuration option on the latest instrumentation version -> to opt-in (revert) to the old conventions, or it can be provided by patching old -> instrumentation versions for security-related issues during this overlap. +> adopts the latest HTTP semantic conventions, the prior version SHOULD still be +> supported (e.g. security patches) for 3-months (an opt-out flag on the latest +> instrumentation to emit the prior HTTP semantic conventions during this time is ok). +> The purpose of this time period is to give users time to migrate. ## Name From 7d7d79e7d315fb0cdb874881aa213e0587df5f85 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 11 Apr 2023 15:05:32 -0700 Subject: [PATCH 3/3] Reduce time --- specification/metrics/semantic_conventions/http-metrics.md | 4 ++-- specification/trace/semantic_conventions/http.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index e6dd7ffec6d..543263d64ee 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -29,11 +29,11 @@ operations. By adding HTTP attributes to metric events it allows for finely tune > **Warning** > HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than > [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) -> until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions +> until August 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions > during this time is ok). The purpose of this time period is to give vendors time > to support the new conventions. > -> After October 1, 2023, whenever an HTTP instrumentation published from +> After August 1, 2023, whenever an HTTP instrumentation published from > [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) > adopts the latest HTTP semantic conventions, the prior version SHOULD still be > supported (e.g. security patches) for 3-months (an opt-out flag on the latest diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index e4d95789e39..712cb7fd136 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -30,11 +30,11 @@ and various HTTP versions like 1.1, 2 and SPDY. > **Warning** > HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than > [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md) -> until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions +> until August 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions > during this time is ok). The purpose of this time period is to give vendors time > to support the new conventions. > -> After October 1, 2023, whenever an HTTP instrumentation published from +> After August 1, 2023, whenever an HTTP instrumentation published from > [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories) > adopts the latest HTTP semantic conventions, the prior version SHOULD still be > supported (e.g. security patches) for 3-months (an opt-out flag on the latest