From f0d46c382080dcec6d3335606c40a5a82d7b744e 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     | 25 ++++++++++++++++++++++---
 model/metrics/system-metrics.yaml | 16 +++++++++++++---
 3 files changed, 40 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..67cf6c92fc 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -157,7 +157,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 +172,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -177,6 +179,23 @@ 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 +215,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -752,6 +770,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..9a7907ccb2 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,11 +103,23 @@ 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