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

Hide file tree

Showing 3 changed files with 33 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 adopt any breaking changes from the future versions of the system
+>   conventions 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,17 @@ 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 adopt any breaking changes from the future versions of this
+>   document system 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,17 @@ 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 adopt any breaking changes from the future versions of this
+>   document system 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`.