From aac8c7ea3e3817b2ba474edb3867710fadbaed82 Mon Sep 17 00:00:00 2001
From: Pablo Baeyens <pablo.baeyens@datadoghq.com>
Date: Mon, 16 Oct 2023 17:16:05 +0200
Subject: [PATCH] Clarify how to report the total amount of memory

---
 CHANGELOG.md                      |  5 +++++
 docs/system/system-metrics.md     | 24 +++++++++++++++++++++---
 model/metrics/system-metrics.yaml | 16 +++++++++++++---
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2efc35c494..2434a00b8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,9 +11,14 @@ release.
 
 - BREAKING: Rename http.resend_count to http.request.resend_count.
   ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374))
+- 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
 
+- Add opt-in `system.memory.limit` metric.
+  ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409))
+
 ### Fixes
 
 - Clarify that `error.type` should be the fully-qualified exception class name
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index c92dff04e5..8e019d93b8 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -28,6 +28,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
   * [Metric: `system.cpu.logical.count`](#metric-systemcpulogicalcount)
 - [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)
@@ -157,7 +158,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) -->
@@ -169,7 +173,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -177,6 +180,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].
@@ -196,7 +214,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -752,6 +769,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 cfd20979f2..7462d21b7e 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -87,8 +87,6 @@ groups:
         type:
           allow_custom_values: true
           members:
-            - id: total
-              value: 'total'
             - id: used
               value: 'used'
             - id: free
@@ -105,12 +103,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