Add system.linux.memory.available metric

CHANGELOG.md

@@ -100,6 +100,8 @@ release.
     - `state` to `system.network.state`
   - Rename attributes for `system.processes.*` metrics:
     - `status` to `system.processes.status`
+- Add `system.linux.memory.available` metric.
+  ([#323](https://github.com/open-telemetry/semantic-conventions/pull/323))
 
 ## v1.21.0 (2023-07-13)
 

CONTRIBUTING.md

@@ -21,18 +21,18 @@ key, but non-obvious, aspects:
 - All descriptions, normative language are defined in the `docs/`
   directory.
   - We provide tooling to generate Markdown documentation from the formal
-    YAML definitons.  See [Yaml to Markdown](#yaml-to-markdown).
+    YAML definitons. See [Yaml to Markdown](#yaml-to-markdown).
   - We use Hugo to render [semantic conventions on our website](https://opentelemetry.io/docs/specs/semconv/).
     You will see `<!--- Hugo front matter used to generate ...` sections
-    in markdown.  See [Hugo frontmatter](#hugo-frontmatter) for details.
+    in markdown. See [Hugo frontmatter](#hugo-frontmatter) for details.
 - All changes to existing attributes, metrics, etc. MUST be allowed as
   per our [stability guarantees](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/versioning-and-stability.md#semantic-conventions-stability) and
-  defined in a schema file.  As part of any contribution, you should
+  defined in a schema file. As part of any contribution, you should
   include attribute changes defined in the `schema-next.yaml` file.
   For details, please read [the schema specification](https://opentelemetry.io/docs/specs/otel/schemas/).
 - After creating a pull request, please update the [CHANGELOG](CHANGELOG.md) file with
   a description of your changes.
-  
+
 Please make sure all Pull Requests are compliant with these rules!
 
 ### Hugo frontmatter

docs/system/system-metrics.md

@@ -47,6 +47,7 @@ instruments not explicitly defined in the specification.
   * [Metric: `system.processes.count`](#metric-systemprocessescount)
   * [Metric: `system.processes.created`](#metric-systemprocessescreated)
 - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics)
+  * [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable)
 
 <!-- tocstop -->
 
@@ -739,3 +740,17 @@ an `{os}` prefix to split this metric across OSes.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/document-status.md
 [MetricRecommended]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.22.0/specification/metrics/metric-requirement-level.md#recommended
+
+### Metric: `system.linux.memory.available`
+
+<!-- semconv metric.system.linux.memory.available(metric_table) -->
+| Name     | Instrument Type | Unit (UCUM) | Description    |
+| -------- | --------------- | ----------- | -------------- |
+| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping [1] |
+
+**[1]:** This is an alternative to `system.memory.usage` metric with `state=free`.
+Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values.
+This is supposed to be more accurate than just "free" memory.
+People who are not experts in Linux Kernel are not expected to know the precise formula. For reference, see the calculations [here](https://superuser.com/a/980821).
+See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+<!-- endsemconv -->

model/metrics/system-metrics.yaml

@@ -490,3 +490,17 @@ groups:
     brief: "Total number of processes created over uptime of the host"
     instrument: counter
     unit: "{process}"
+
+  # system.linux.* metrics
+  - id: metric.system.linux.memory.available
+    type: metric
+    metric_name: system.linux.memory.available
+    brief: "An estimate of how much memory is available for starting new applications, without causing swapping"
+    note: |
+      This is an alternative to `system.memory.usage` metric with `state=free`.
+      Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values.
+      This is supposed to be more accurate than just "free" memory.
+      People who are not experts in Linux Kernel are not expected to know the precise formula. For reference, see the calculations [here](https://superuser.com/a/980821).
+      See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+    instrument: updowncounter
+    unit: "By"