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 · 36035a1 · 36035a1
1 parent 40839cb
commit 36035a1
Show file tree

Hide file tree

Showing 3 changed files with 31 additions and 0 deletions.
diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md
@@ -33,6 +33,17 @@ when creating instruments not explicitly defined in the specification.
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing instrumentations and collector that are using
+> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/tree/v1.21.0/docs/system/hardware-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 instrumentations and collector that are using
+> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/tree/v1.21.0/docs/system/process-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 instrumentations and collector that are using
+> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/tree/v1.21.0/docs/system/system-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`.