From 75f9d428a45f9e779b72c34d9ac3c00625b7472a Mon Sep 17 00:00:00 2001
From: Dmitrii Anoshin <anoshindx@gmail.com>
Date: Mon, 8 Jan 2024 14:31:40 -0800
Subject: [PATCH] Add a warning to the system semantic conventions (#579)

---
 docs/system/hardware-metrics.md | 11 +++++++++++
 docs/system/process-metrics.md  | 10 ++++++++++
 docs/system/system-metrics.md   | 10 ++++++++++
 3 files changed, 31 insertions(+)

diff --git a/docs/system/hardware-metrics.md b/docs/system/hardware-metrics.md
index 904dd8c74..09ba773b6 100644
--- 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<!-- markdown-link-check-disable-next-line -->
+> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/hardware-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT adopt any breaking changes from document 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
index 431263196..c61976371 100644
--- 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<!-- markdown-link-check-disable-next-line -->
+> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/process-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT adopt any breaking changes from document 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
index 59dd80849..4f682cc03 100644
--- 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<!-- markdown-link-check-disable-next-line -->
+> [v1.21.0 of this document](https://github.com/open-telemetry/semantic-conventions/blob/v1.21.0/docs/system/system-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT adopt any breaking changes from document 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`.