add system.linux.memory.slab to system metrics (#1078)

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com> Co-authored-by: Alexandra Konrad <alexandra.konrad@elastic.co> Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
2024-07-29 17:37:10 +02:00 · 2024-07-29 17:37:10 +02:00 · a44ff76871
parent 2ac36a57a1
commit a44ff76871
9 changed files with 134 additions and 0 deletions
--- a/.chloggen/add_linux_memory_slab.yaml
+++ b/.chloggen/add_linux_memory_slab.yaml
@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: linux
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add the `system.linux.memory.slab.usage` metric and the `linux.memory.slab.state` attributes.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [531]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
--- a/.github/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yaml
@ -52,6 +52,7 @@ body:
        - area:http
        - area:jvm
        - area:k8s
+        - area:linux
        - area:log
        - area:messaging
        - area:network
--- a/.github/ISSUE_TEMPLATE/change_proposal.yaml
+++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@ -45,6 +45,7 @@ body:
        - area:http
        - area:jvm
        - area:k8s
+        - area:linux
        - area:log
        - area:messaging
        - area:network
--- a/.github/ISSUE_TEMPLATE/new-conventions.yaml
+++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@ -54,6 +54,7 @@ body:
        - area:http
        - area:jvm
        - area:k8s
+        - area:linux
        - area:log
        - area:messaging
        - area:network
--- a/docs/attributes-registry/README.md
+++ b/docs/attributes-registry/README.md
@ -66,6 +66,7 @@ Currently, the following namespaces exist:
 - [iOS](ios.md)
 - [JVM](jvm.md)
 - [K8s](k8s.md)
+- [Linux](linux.md)
 - [Log](log.md)
 - [Messaging](messaging.md)
 - [Network](network.md)
--- a/docs/attributes-registry/linux.md
+++ b/docs/attributes-registry/linux.md
@ -0,0 +1,22 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Linux
+
+## Linux Memory Attributes
+
+Describes Linux Memory attributes
+
+| Attribute                 | Type   | Description                 | Examples                       | Stability                                                        |
+| ------------------------- | ------ | --------------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value           | Description   | Stability                                                        |
+| --------------- | ------------- | ---------------------------------------------------------------- |
+| `reclaimable`   | reclaimable   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
--- a/docs/system/system-metrics.md
+++ b/docs/system/system-metrics.md
@ -57,6 +57,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
  - [Metric: `system.process.created`](#metric-systemprocesscreated)
 - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics)
  - [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable)
+  - [Metric: `system.linux.memory.slab.usage`](#metric-systemlinuxmemoryslabusage)

 <!-- tocstop -->

@ -1475,6 +1476,58 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5



+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `system.linux.memory.slab.usage`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.system.linux.memory.slab.usage(metric_table) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `system.linux.memory.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system.
+Note that the total slab memory is not constant and may vary over time.
+See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+<!-- semconv metric.system.linux.memory.slab.usage(full) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`linux.memory.slab.state`](/docs/attributes-registry/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value  | Description | Stability |
+|---|---|---|
+| `reclaimable` | reclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
--- a/model/metrics/system-metrics.yaml
+++ b/model/metrics/system-metrics.yaml
@ -342,3 +342,17 @@ groups:
    instrument: updowncounter
    unit: "By"
    attributes: []
+
+  - id: metric.system.linux.memory.slab.usage
+    type: metric
+    metric_name: system.linux.memory.slab.usage
+    stability: experimental
+    brief: "Reports the memory used by the Linux kernel for managing caches of frequently used objects."
+    note: |
+      The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system.
+      Note that the total slab memory is not constant and may vary over time.
+      See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+    instrument: updowncounter
+    unit: "By"
+    attributes:
+      - ref: linux.memory.slab.state
--- a/model/registry/linux.yaml
+++ b/model/registry/linux.yaml
@ -0,0 +1,19 @@
+groups:
+  # linux.memory.* attribute group
+  - id: registry.linux.memory
+    prefix: linux.memory
+    type: attribute_group
+    brief: "Describes Linux Memory attributes"
+    attributes:
+      - id: slab.state
+        type:
+          members:
+            - id: reclaimable
+              value: 'reclaimable'
+              stability: experimental
+            - id: unreclaimable
+              value: 'unreclaimable'
+              stability: experimental
+        stability: experimental
+        brief: "The Linux Slab memory state"
+        examples: ["reclaimable", "unreclaimable"]