Clarify how to report the total amount of memory

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

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,14 +172,28 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
 | `buffers` | buffers |
 | `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 +213,6 @@ This metric is [recommended][MetricRecommended].
 
 | Value  | Description |
 |---|---|
-| `total` | total |
 | `used` | used |
 | `free` | free |
 | `shared` | shared |
@@ -752,6 +768,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`
 

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