Add the system.filesystem.limit metric (#1380)

open-telemetry · Sep 16, 2024 · 3b1b4a4 · 3b1b4a4
1 parent 156daec
commit 3b1b4a4
Show file tree

Hide file tree

Showing 3 changed files with 107 additions and 4 deletions.
diff --git a/.chloggen/add_filesystem_limit.yaml b/.chloggen/add_filesystem_limit.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: system
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add the `system.filesystem.limit` metric
+
+# 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: [127]
+
+# (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:
diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
@@ -47,6 +47,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
 - [Filesystem Metrics](#filesystem-metrics)
   - [Metric: `system.filesystem.usage`](#metric-systemfilesystemusage)
   - [Metric: `system.filesystem.utilization`](#metric-systemfilesystemutilization)
+  - [Metric: `system.filesystem.limit`](#metric-systemfilesystemlimit)
 - [Network Metrics](#network-metrics)
   - [Metric: `system.network.dropped`](#metric-systemnetworkdropped)
   - [Metric: `system.network.packets`](#metric-systemnetworkpackets)
@@ -977,7 +978,12 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `system.filesystem.usage` | UpDownCounter | `By` |  | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `system.filesystem.usage` | UpDownCounter | `By` | Reports a filesystem's space usage across different states. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+**[1]:** The sum of all `system.filesystem.usage` values over the different `system.filesystem.state` attributes
+SHOULD equal the total storage capacity of the filesystem, that is `system.filesystem.limit`.
+
 
 
 <!-- markdownlint-restore -->
@@ -994,7 +1000,7 @@ This metric is [recommended][MetricRecommended].
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`system.device`](/docs/attributes-registry/system.md) | string | Identifier for the device where the filesystem resides. | `/dev/sda`; `\network-drive` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`system.filesystem.mode`](/docs/attributes-registry/system.md) | string | The filesystem mode | `rw, ro` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`system.filesystem.mountpoint`](/docs/attributes-registry/system.md) | string | The filesystem mount path | `/mnt/data` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`system.filesystem.state`](/docs/attributes-registry/system.md) | string | The filesystem state | `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -1057,7 +1063,7 @@ This metric is [recommended][MetricRecommended].
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
-| [`system.device`](/docs/attributes-registry/system.md) | string | The device identifier | `(identifier)` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`system.device`](/docs/attributes-registry/system.md) | string | Identifier for the device where the filesystem resides. | `/dev/sda`; `\network-drive` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`system.filesystem.mode`](/docs/attributes-registry/system.md) | string | The filesystem mode | `rw, ro` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`system.filesystem.mountpoint`](/docs/attributes-registry/system.md) | string | The filesystem mount path | `/mnt/data` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | [`system.filesystem.state`](/docs/attributes-registry/system.md) | string | The filesystem state | `used` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -1085,6 +1091,59 @@ This metric is [recommended][MetricRecommended].
 
 
 
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `system.filesystem.limit`
+
+This metric is [opt-in][MetricOptIn].
+
+<!-- semconv metric.system.filesystem.limit(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.filesystem.limit` | UpDownCounter | `By` | The total storage capacity of the filesystem | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+<!-- semconv metric.system.filesystem.limit -->
+<!-- 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 |
+|---|---|---|---|---|---|
+| [`system.device`](/docs/attributes-registry/system.md) | string | Identifier for the device where the filesystem resides. | `/dev/sda`; `\network-drive` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`system.filesystem.mode`](/docs/attributes-registry/system.md) | string | The filesystem mode | `rw, ro` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`system.filesystem.mountpoint`](/docs/attributes-registry/system.md) | string | The filesystem mount path | `/mnt/data` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`system.filesystem.type`](/docs/attributes-registry/system.md) | string | The filesystem type | `ext4` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`system.filesystem.type` 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 |
+|---|---|---|
+| `exfat` | exfat | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `ext4` | ext4 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `fat32` | fat32 | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `hfsplus` | hfsplus | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `ntfs` | ntfs | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `refs` | refs | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->

diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
@@ -224,11 +224,16 @@ groups:
     type: metric
     metric_name: system.filesystem.usage
     stability: experimental
-    brief: ""
+    brief: "Reports a filesystem's space usage across different states."
+    note: |
+      The sum of all `system.filesystem.usage` values over the different `system.filesystem.state` attributes
+      SHOULD equal the total storage capacity of the filesystem, that is `system.filesystem.limit`.
     instrument: updowncounter
     unit: "By"
     attributes:
       - ref: system.device
+        brief: Identifier for the device where the filesystem resides.
+        examples: ["/dev/sda", "\\network-drive"]
       - ref: system.filesystem.state
       - ref: system.filesystem.type
       - ref: system.filesystem.mode
@@ -243,11 +248,28 @@ groups:
     unit: "1"
     attributes:
       - ref: system.device
+        brief: Identifier for the device where the filesystem resides.
+        examples: ["/dev/sda", "\\network-drive"]
       - ref: system.filesystem.state
       - ref: system.filesystem.type
       - ref: system.filesystem.mode
       - ref: system.filesystem.mountpoint
 
+  - id: metric.system.filesystem.limit
+    type: metric
+    metric_name: system.filesystem.limit
+    stability: experimental
+    brief: "The total storage capacity of the filesystem"
+    instrument: updowncounter
+    unit: "By"
+    attributes:
+      - ref: system.device
+        brief: Identifier for the device where the filesystem resides.
+        examples: ["/dev/sda", "\\network-drive"]
+      - ref: system.filesystem.type
+      - ref: system.filesystem.mode
+      - ref: system.filesystem.mountpoint
+
   # system.network.* metrics
   - id: metric.system.network.dropped
     type: metric