From fa83617b4778d9d7af686afd339b1313a578491b Mon Sep 17 00:00:00 2001
From: Mike Koltsov <6823298+ItsLastDay@users.noreply.github.com>
Date: Wed, 13 Sep 2023 11:40:32 +0200
Subject: [PATCH 1/8] Add system.linux.memory.available to system-metrics.yaml

---
 model/metrics/system-metrics.yaml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
index 41c508f3d2..bde13eaa52 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -490,3 +490,13 @@ 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 swapping"
+    note: |
+      Available since Linux 3.14: see `MemAvailable` in https://man7.org/linux/man-pages/man5/proc.5.html.
+    instrument: updowncounter
+    unit: "By"  

From ad186d53631cb31af046278d71929df784755b87 Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Wed, 13 Sep 2023 09:55:24 +0000
Subject: [PATCH 2/8] Amend changelog

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96acda87f4..dcaabe9526 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-# Changelog
+asdfdsf# Changelog
 
 Please update changelog as part of any significant pull request. Place short
 description of your change into "Unreleased" section. As part of release process

From 8454416bb65310bc1e9c6c9eba7744014966e2e7 Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Wed, 13 Sep 2023 11:05:04 +0000
Subject: [PATCH 3/8] Update system-metrics.md

I used `make table-generation`, and manually updated ToC.
---
 docs/system/system-metrics.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index f17b799050..07929073fc 100644
--- a/docs/system/system-metrics.md
+++ b/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,13 @@ 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 swapping [1] |
+
+**[1]:** Available since Linux 3.14: see `MemAvailable` in https://man7.org/linux/man-pages/man5/proc.5.html.
+<!-- endsemconv -->

From 3321a2309fd7b23b72cf542edc4c0fce64e531b4 Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Wed, 13 Sep 2023 11:24:17 +0000
Subject: [PATCH 4/8] Apply changes from `make fix`

---
 CHANGELOG.md                      | 2 +-
 CONTRIBUTING.md                   | 8 ++++----
 docs/system/system-metrics.md     | 2 +-
 model/metrics/system-metrics.yaml | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dcaabe9526..96acda87f4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-asdfdsf# Changelog
+# Changelog
 
 Please update changelog as part of any significant pull request. Place short
 description of your change into "Unreleased" section. As part of release process
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5721670ffa..3bfe45c930 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index 07929073fc..4de5ca82cf 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -748,5 +748,5 @@ an `{os}` prefix to split this metric across OSes.
 | -------- | --------------- | ----------- | -------------- |
 | `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without swapping [1] |
 
-**[1]:** Available since Linux 3.14: see `MemAvailable` in https://man7.org/linux/man-pages/man5/proc.5.html.
+**[1]:** Available since Linux 3.14: see `MemAvailable` in [here](https://man7.org/linux/man-pages/man5/proc.5.html).
 <!-- endsemconv -->
diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
index bde13eaa52..bfb5bec72c 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -497,6 +497,6 @@ groups:
     metric_name: system.linux.memory.available
     brief: "An estimate of how much memory is available for starting new applications, without swapping"
     note: |
-      Available since Linux 3.14: see `MemAvailable` in https://man7.org/linux/man-pages/man5/proc.5.html.
+      Available since Linux 3.14: see `MemAvailable` in [here](https://man7.org/linux/man-pages/man5/proc.5.html).
     instrument: updowncounter
-    unit: "By"  
+    unit: "By"

From 8db13b340a4c95628cd43c702c96ecbaa33e5134 Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Wed, 13 Sep 2023 11:26:18 +0000
Subject: [PATCH 5/8] Add my change to changelog

---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96acda87f4..46f14d6230 100644
--- a/CHANGELOG.md
+++ b/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)
 

From 5168d61ac91972f3f3b51eccf7f73ffec1a5848b Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Thu, 14 Sep 2023 10:00:07 +0000
Subject: [PATCH 6/8] Expand note about "free" vs "available"

---
 docs/system/system-metrics.md     | 7 +++++--
 model/metrics/system-metrics.yaml | 7 +++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index 4de5ca82cf..82ab952777 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -746,7 +746,10 @@ an `{os}` prefix to split this metric across OSes.
 <!-- 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 swapping [1] |
+| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping [1] |
 
-**[1]:** Available since Linux 3.14: see `MemAvailable` in [here](https://man7.org/linux/man-pages/man5/proc.5.html).
+**[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 -->
diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
index 291735b3a3..c88081efb1 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -495,8 +495,11 @@ groups:
   - 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 swapping"
+    brief: "An estimate of how much memory is available for starting new applications, without causing swapping"
     note: |
-      Available since Linux 3.14: see `MemAvailable` in [here](https://man7.org/linux/man-pages/man5/proc.5.html).
+      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"

From 6ab6d78ce509483b93a4691fc51f1b94c5d029af Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Fri, 15 Sep 2023 13:07:18 +0000
Subject: [PATCH 7/8] Fix yamllint error

The line was too long.
---
 docs/system/system-metrics.md     | 3 ++-
 model/metrics/system-metrics.yaml | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index 82ab952777..5a9ea3b208 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -749,7 +749,8 @@ an `{os}` prefix to split this metric across OSes.
 | `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.
+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 -->
diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
index c88081efb1..fae65e1d2b 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -498,7 +498,8 @@ groups:
     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.
+      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

From 719cfbe1f314e0783601bd4fc6b913885d63596a Mon Sep 17 00:00:00 2001
From: Mike Koltsov <ild@google.com>
Date: Mon, 18 Sep 2023 11:47:06 +0000
Subject: [PATCH 8/8] Remove note "People who are not experts in Linux Kernel
 are not expected to know the precise formula"

---
 docs/system/system-metrics.md     | 2 +-
 model/metrics/system-metrics.yaml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
index 5a9ea3b208..37b14608a1 100644
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@@ -751,6 +751,6 @@ an `{os}` prefix to split this metric across OSes.
 **[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).
+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 -->
diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
index fae65e1d2b..cfd20979f2 100644
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@@ -500,7 +500,7 @@ groups:
       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).
+      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"