From 131637a718a5d6e0a29e1cbf503637dd2dfd343e Mon Sep 17 00:00:00 2001
From: Pablo Baeyens <pablo.baeyens@datadoghq.com>
Date: Fri, 27 Oct 2023 10:31:00 +0200
Subject: [PATCH] Clarify how to report the total amount of memory (#409)

Co-authored-by: Alexander Wert <AlexanderWert@users.noreply.github.com>
---
 CHANGELOG.md                      |  4 ++++
 docs/system/system-metrics.md     | 24 +++++++++++++++++++++---
 model/metrics/system-metrics.yaml | 16 +++++++++++++---
 3 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7e7f656d5..96a01635d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,8 @@ release.
   ([#429](https://github.com/open-telemetry/semantic-conventions/pull/429))
 - Use seconds as default duration for FaaS duration histograms
   ([#384](https://github.com/open-telemetry/semantic-conventions/pull/384))
+- BREAKING: Remove `total` from list of well-known values of `system.memory.state` attribute.
+  ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409))
 
 ### Features
 
@@ -35,6 +37,8 @@ release.
   ([#348](https://github.com/open-telemetry/semantic-conventions/pull/348))
 - Metric namespaces SHOULD NOT be pluralized.
   ([#267](https://github.com/open-telemetry/opentelemetry-specification/pull/267))
+- Add opt-in `system.memory.limit` metric.
+  ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409))
 
 ### Fixes
 
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index c7bdd1703f..d5848d424d 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -29,6 +29,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
   * [Metric: `system.cpu.frequency`](#metric-systemcpufrequency)
 - [Memory Metrics](#memory-metrics)
   * [Metric: `system.memory.usage`](#metric-systemmemoryusage)
+  * [Metric: `system.memory.limit`](#metric-systemmemorylimit)
   * [Metric: `system.memory.utilization`](#metric-systemmemoryutilization)
 - [Paging/Swap Metrics](#pagingswap-metrics)
   * [Metric: `system.paging.usage`](#metric-systempagingusage)
@@ -174,7 +175,10 @@ This metric is [recommended][MetricRecommended].
 <!-- semconv metric.system.memory.usage(metric_table) -->
 | Name     | Instrument Type | Unit (UCUM) | Description    |
 | -------- | --------------- | ----------- | -------------- |
-| `system.memory.usage` | UpDownCounter | `By` |  |
+| `system.memory.usage` | UpDownCounter | `By` | Reports memory in use by state. [1] |
+
+**[1]:** The sum over all `system.memory.state` values SHOULD equal the total memory
+available on the system, that is `system.memory.limit`.
 <!-- endsemconv -->
 
 <!-- semconv metric.system.memory.usage(full) -->
@@ -186,7 +190,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -194,6 +197,21 @@ This metric is [recommended][MetricRecommended].
 | `cached` | cached |
 <!-- endsemconv -->
 
+### Metric: `system.memory.limit`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.system.memory.limit(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `system.memory.limit` | UpDownCounter | `By` | Total memory available in the system. [1] |
+
+**[1]:** Its value SHOULD equal the sum of `system.memory.state` over all states.
+<!-- endsemconv -->
+
+<!-- semconv metric.system.memory.limit(full) -->
+<!-- endsemconv -->
+
 ### Metric: `system.memory.utilization`
 
 This metric is [recommended][MetricRecommended].
@@ -213,7 +231,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -769,6 +786,7 @@ an `{os}` prefix to split this metric across OSes.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md
 [MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/metrics/metric-requirement-level.md#recommended
+[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in
 
 ### Metric: `system.linux.memory.available`
 
diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
index 9f582e4b19..d3c761b0b9 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -96,8 +96,6 @@ groups:
         type:
           allow_custom_values: true
           members:
-            - id: total
-              value: 'total'
             - id: used
               value: 'used'
             - id: free
@@ -114,12 +112,24 @@ groups:
   - id: metric.system.memory.usage
     type: metric
     metric_name: system.memory.usage
-    brief: ""
+    brief: "Reports memory in use by state."
+    note: |
+      The sum over all `system.memory.state` values SHOULD equal the total memory
+      available on the system, that is `system.memory.limit`.
     instrument: updowncounter
     unit: "By"
     attributes:
       - ref: system.memory.state
 
+  - id: metric.system.memory.limit
+    type: metric
+    metric_name: system.memory.limit
+    brief: "Total memory available in the system."
+    note: |
+      Its value SHOULD equal the sum of `system.memory.state` over all states.
+    instrument: updowncounter
+    unit: "By"
+
   - id: metric.system.memory.utilization
     type: metric
     metric_name: system.memory.utilization