Add transition plan for upcoming breaking changes to the unstable HTT…

…P semantic conventions
open-telemetry · Apr 11, 2023 · c3eef69 · c3eef69
1 parent b0ba0a9
commit c3eef69
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 0 deletions.
diff --git 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
@@ -26,6 +26,20 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 
 <!-- tocstop -->
 
+> **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
@@ -27,6 +27,20 @@ and various HTTP versions like 1.1, 2 and SPDY.
 
 <!-- tocstop -->
 
+> **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).