Add a warning to the system semantic conventions

Add a warning the system semantic conventions to prevent implementations from adopting the breaking changes until the conventions are stabilized. This warning is to be updated once open-telemetry#246 is closed
dmitryax · Dec 4, 2023 · c6475cc · c6475cc
1 parent 40839cb
commit c6475cc
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 2 deletions.
diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md
@@ -26,8 +26,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 
 <!-- tocstop -->
 
-> **Warning**
-> Existing HTTP instrumentations that are using
+> **Warning** Existing HTTP instrumentations that are using
 > [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):
 >

diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md
@@ -33,6 +33,16 @@ when creating instruments not explicitly defined in the specification.
 
 <!-- tocstop -->
 
+> **Warning** Existing HTTP instrumentations that are using
+> [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):
+>
+> * SHOULD NOT change the version of the system conventions that they emit
+>   until the system semantic conventions are marked stable. Conventions include, 
+>   but are not limited to, attributes, metric names, and unit of measure.
+> * SHOULD introduce a control mechanism to allow users to opt-in to the new
+>   conventions once the migration plan is finalized.
+
 ## Common hardware attributes
 
 All metrics in `hw.` instruments should be attached to a [Host Resource](/docs/resource/host.md)

diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md
@@ -25,6 +25,16 @@ metrics](/docs/runtime/README.md#metrics).
 
 <!-- tocstop -->
 
+> **Warning** Existing HTTP instrumentations that are using
+> [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):
+>
+> * SHOULD NOT change the version of the system conventions that they emit
+>   until the system semantic conventions are marked stable. Conventions include, 
+>   but are not limited to, attributes, metric names, and unit of measure.
+> * SHOULD introduce a control mechanism to allow users to opt-in to the new
+>   conventions once the migration plan is finalized.
+
 ## Metric Instruments
 
 ### Process

diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
@@ -59,6 +59,16 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
 
 <!-- tocstop -->
 
+> **Warning** Existing HTTP instrumentations that are using
+> [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):
+>
+> * SHOULD NOT change the version of the system conventions that they emit
+>   until the system semantic conventions are marked stable. Conventions include, 
+>   but are not limited to, attributes, metric names, and unit of measure.
+> * SHOULD introduce a control mechanism to allow users to opt-in to the new
+>   conventions once the migration plan is finalized.
+
 ## Processor Metrics
 
 **Description:** System level processor metrics captured under the namespace `system.cpu`.