From 47d6ac8beb6f106edb48bae36ae28c84f3fa4c58 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Sat, 11 Apr 2026 14:15:38 -0700 Subject: [PATCH 01/12] Add support for filesystem lock metrics --- .chloggen/filesystem-locks.yaml | 22 ++++++++++++++++++++++ model/file/registry.yaml | 30 ++++++++++++++++++++++++++++++ model/system/metrics.yaml | 20 ++++++++++++++++++++ 3 files changed, 72 insertions(+) create mode 100644 .chloggen/filesystem-locks.yaml diff --git a/.chloggen/filesystem-locks.yaml b/.chloggen/filesystem-locks.yaml new file mode 100644 index 0000000000..9f6e82ac8e --- /dev/null +++ b/.chloggen/filesystem-locks.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.filesystem, file.lock + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add support for filesystem lock counts + +# 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: [3611] + +# (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/model/file/registry.yaml b/model/file/registry.yaml index d66188da47..83a8da1bd5 100644 --- a/model/file/registry.yaml +++ b/model/file/registry.yaml @@ -137,3 +137,33 @@ groups: This attribute is only applicable to symbolic links. stability: development examples: ['/usr/bin/python3'] + - id: registry.file.lock + type: attribute_group + display_name: File locks + brief: > + These attributes may be used for any filesystem lock or related operation + attributes: + - id: file.lock.type + type: + members: + - id: read + value: 'read' + stability: development + - id: write + value: 'write' + stability: development + stability: development + brief: "The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" + examples: ["read"] + - id: file.lock.class + type: string + brief: > + Class of lock or operation + stability: development + examples: ["POSIX", "FLOCK", "DELEG", "LEASE"] + - id: file.lock.mode + type: string + brief: > + Mode of lock or operation + stability: development + examples: ["ADVISORY", "MANDATORY", "BREAKING", "ACTIVE", "BREAKER"] diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index e72dc9a5a9..6414fe1713 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -384,6 +384,26 @@ groups: entity_associations: - host + - id: metric.system.filesystem.locks.count + type: metric + metric_name: system.filesystem.locks.count + annotations: + code_generation: + metric_value_type: int + stability: development + brief: "Filesystem lock counts." + instrument: updowncounter + unit: "{lock}" + attributes: + - ref: system.device + brief: OS-specific identifier for the device where the filesystem resides. + examples: ["08:01"] + - ref: file.lock.type + - ref: file.lock.class + - ref: file.lock.mode + entity_associations: + - host + # system.network.* metrics - id: metric.system.network.packet.dropped type: metric From 1b0b2d9345c1cdd85bf7c089843bddee5067079c Mon Sep 17 00:00:00 2001 From: John Leslie Date: Sat, 11 Apr 2026 15:50:49 -0700 Subject: [PATCH 02/12] add system.filesystem.locks and file.lock --- docs/registry/attributes/file.md | 24 ++++++++++++++++++++++++ model/system/metrics.yaml | 2 +- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/registry/attributes/file.md b/docs/registry/attributes/file.md index 2fbde24ff6..205c7e97f5 100644 --- a/docs/registry/attributes/file.md +++ b/docs/registry/attributes/file.md @@ -3,6 +3,9 @@ # File +- [File Attributes](#file-attributes) +- [File locks](#file-locks) + ## File Attributes Describes file attributes. @@ -44,3 +47,24 @@ Describes file attributes. On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default data stream for a file is just called $DATA. Zone.Identifier is commonly used by Windows to track contents downloaded from the Internet. An ADS is typically of the form: C:\path\to\filename.extension:some_fork_name, and some_fork_name is the value that should populate `fork_name`. `filename.extension` should populate `file.name`, and `extension` should populate `file.extension`. The full path, `file.path`, will include the fork name. **[7] `file.symbolic_link.target_path`:** This attribute is only applicable to symbolic links. + +## File locks + +These attributes may be used for any filesystem lock or related operation + +**Attributes:** + +| Key | Stability | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | +| `file.lock.class` | ![Development](https://img.shields.io/badge/-development-blue) | string | Class of lock or operation | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| `file.lock.mode` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | +| `file.lock.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | + +--- + +`file.lock.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 | +| --- | --- | --- | +| `read` | read | ![Development](https://img.shields.io/badge/-development-blue) | +| `write` | write | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index 6414fe1713..d33d57dca5 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -396,7 +396,7 @@ groups: unit: "{lock}" attributes: - ref: system.device - brief: OS-specific identifier for the device where the filesystem resides. + brief: OS-specific identifier for the device where the file resides. examples: ["08:01"] - ref: file.lock.type - ref: file.lock.class From 4589edfe487f1999746defaa0c5c60217fa3f482 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 01:10:01 -0700 Subject: [PATCH 03/12] s/file.lock.class/file.lock.mechanism/ --- model/file/registry.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/model/file/registry.yaml b/model/file/registry.yaml index 83a8da1bd5..f0a6792e7b 100644 --- a/model/file/registry.yaml +++ b/model/file/registry.yaml @@ -155,10 +155,10 @@ groups: stability: development brief: "The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" examples: ["read"] - - id: file.lock.class + - id: file.lock.mechanism type: string brief: > - Class of lock or operation + Mechanism of lock or operation stability: development examples: ["POSIX", "FLOCK", "DELEG", "LEASE"] - id: file.lock.mode From be361d1469db726c32d185882619cc50d306fb1f Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 01:11:14 -0700 Subject: [PATCH 04/12] s/file.lock.class/file.lock.mechanism/ --- docs/registry/attributes/file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/registry/attributes/file.md b/docs/registry/attributes/file.md index 205c7e97f5..8a5f7e94a1 100644 --- a/docs/registry/attributes/file.md +++ b/docs/registry/attributes/file.md @@ -56,7 +56,7 @@ These attributes may be used for any filesystem lock or related operation | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `file.lock.class` | ![Development](https://img.shields.io/badge/-development-blue) | string | Class of lock or operation | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mechanism of lock or operation | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | | `file.lock.mode` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | | `file.lock.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | From e07b5715f2b0a119e35b404944f2db07fe41f449 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 01:11:40 -0700 Subject: [PATCH 05/12] s/file.lock.class/file.lock.mechanism/ --- model/system/metrics.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index d33d57dca5..ea4e8987a2 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -399,7 +399,7 @@ groups: brief: OS-specific identifier for the device where the file resides. examples: ["08:01"] - ref: file.lock.type - - ref: file.lock.class + - ref: file.lock.mechanism - ref: file.lock.mode entity_associations: - host From 4138a1f2bcd8a96203553c009c404967fe3c9681 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 01:22:32 -0700 Subject: [PATCH 06/12] update URL --- docs/registry/attributes/file.md | 2 +- model/file/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/registry/attributes/file.md b/docs/registry/attributes/file.md index 8a5f7e94a1..7b976d5a7d 100644 --- a/docs/registry/attributes/file.md +++ b/docs/registry/attributes/file.md @@ -56,7 +56,7 @@ These attributes may be used for any filesystem lock or related operation | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mechanism of lock or operation | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | | `file.lock.mode` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | | `file.lock.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | diff --git a/model/file/registry.yaml b/model/file/registry.yaml index f0a6792e7b..9a539b9733 100644 --- a/model/file/registry.yaml +++ b/model/file/registry.yaml @@ -158,7 +158,7 @@ groups: - id: file.lock.mechanism type: string brief: > - Mechanism of lock or operation + "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" stability: development examples: ["POSIX", "FLOCK", "DELEG", "LEASE"] - id: file.lock.mode From 7bd1455587a5184f285e17ccfdb18915530773bb Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 18:25:57 -0700 Subject: [PATCH 07/12] de-pluralize --- model/system/metrics.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index ea4e8987a2..ad494315ed 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -384,9 +384,9 @@ groups: entity_associations: - host - - id: metric.system.filesystem.locks.count + - id: metric.system.filesystem.lock.count type: metric - metric_name: system.filesystem.locks.count + metric_name: system.filesystem.lock.count annotations: code_generation: metric_value_type: int From 76b2c16924ff837475adc159e593842f1c0769a3 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 18:29:36 -0700 Subject: [PATCH 08/12] add system.filesystem.lock.count to system-metrics.md --- docs/registry/attributes/file.md | 2 +- docs/system/system-metrics.md | 33 ++++++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/registry/attributes/file.md b/docs/registry/attributes/file.md index 7b976d5a7d..757cd0ea50 100644 --- a/docs/registry/attributes/file.md +++ b/docs/registry/attributes/file.md @@ -56,7 +56,7 @@ These attributes may be used for any filesystem lock or related operation | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | | `file.lock.mode` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | | `file.lock.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index aed6abfe51..42aa2e553c 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -827,6 +827,39 @@ This metric is [opt-in][MetricOptIn]. +### Metric: `system.filesystem.lock.count` + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `system.filesystem.lock.count` | UpDownCounter | `{lock}` | Filesystem lock counts. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| --- | --- | --- | --- | --- | --- | +| [`file.lock.mechanism`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| [`file.lock.mode`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | +| [`file.lock.type`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | +| [`system.device`](/docs/registry/attributes/system.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | OS-specific identifier for the device where the file resides. | `08:01` | + +--- + +`file.lock.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 | +| --- | --- | --- | +| `read` | read | ![Development](https://img.shields.io/badge/-development-blue) | +| `write` | write | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + ## Network metrics **Description:** System level network metrics captured under the namespace `system.network`. From 84b9be480f636c943f85a86ac49694475ec2cf76 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 18:32:07 -0700 Subject: [PATCH 09/12] Update model/file/registry.yaml Co-authored-by: Braydon Kains <93549768+braydonk@users.noreply.github.com> --- model/file/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/file/registry.yaml b/model/file/registry.yaml index 9a539b9733..1fc90434a8 100644 --- a/model/file/registry.yaml +++ b/model/file/registry.yaml @@ -139,7 +139,7 @@ groups: examples: ['/usr/bin/python3'] - id: registry.file.lock type: attribute_group - display_name: File locks + display_name: File lock brief: > These attributes may be used for any filesystem lock or related operation attributes: From 485d379a9d669c44e93191a5af26feede242d529 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Mon, 13 Apr 2026 18:45:16 -0700 Subject: [PATCH 10/12] make markdown-toc --- docs/system/system-metrics.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 42aa2e553c..078d409ca9 100644 --- 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 - [Metric: `system.filesystem.usage`](#metric-systemfilesystemusage) - [Metric: `system.filesystem.utilization`](#metric-systemfilesystemutilization) - [Metric: `system.filesystem.limit`](#metric-systemfilesystemlimit) + - [Metric: `system.filesystem.lock.count`](#metric-systemfilesystemlockcount) - [Network metrics](#network-metrics) - [Metric: `system.network.packet.dropped`](#metric-systemnetworkpacketdropped) - [Metric: `system.network.packet.count`](#metric-systemnetworkpacketcount) From d112355c647644bef92f5b1afe500edc1993b8f1 Mon Sep 17 00:00:00 2001 From: John Leslie Date: Tue, 14 Apr 2026 14:19:29 -0700 Subject: [PATCH 11/12] Update model/file/registry.yaml Co-authored-by: Christophe Kamphaus --- model/file/registry.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/model/file/registry.yaml b/model/file/registry.yaml index 1fc90434a8..df33411b8f 100644 --- a/model/file/registry.yaml +++ b/model/file/registry.yaml @@ -157,8 +157,7 @@ groups: examples: ["read"] - id: file.lock.mechanism type: string - brief: > - "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" + brief: "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" stability: development examples: ["POSIX", "FLOCK", "DELEG", "LEASE"] - id: file.lock.mode From 580e1d98f7725edf15357e6cd02f1c6095ba69cb Mon Sep 17 00:00:00 2001 From: John Leslie Date: Wed, 15 Apr 2026 09:28:19 -0700 Subject: [PATCH 12/12] make generate-all && make markdown-toc --- docs/registry/attributes/file.md | 6 +++--- docs/system/system-metrics.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/registry/attributes/file.md b/docs/registry/attributes/file.md index 757cd0ea50..493dfd4eb9 100644 --- a/docs/registry/attributes/file.md +++ b/docs/registry/attributes/file.md @@ -4,7 +4,7 @@ # File - [File Attributes](#file-attributes) -- [File locks](#file-locks) +- [File lock](#file-lock) ## File Attributes @@ -48,7 +48,7 @@ On NTFS, this is analogous to an Alternate Data Stream (ADS), and the default da **[7] `file.symbolic_link.target_path`:** This attribute is only applicable to symbolic links. -## File locks +## File lock These attributes may be used for any filesystem lock or related operation @@ -56,7 +56,7 @@ These attributes may be used for any filesystem lock or related operation | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| `file.lock.mechanism` | ![Development](https://img.shields.io/badge/-development-blue) | string | The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | | `file.lock.mode` | ![Development](https://img.shields.io/badge/-development-blue) | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | | `file.lock.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 078d409ca9..9a05fb0002 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -843,7 +843,7 @@ This metric is [opt-in][MetricOptIn]. | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | -| [`file.lock.mechanism`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)" | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | +| [`file.lock.mechanism`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `POSIX`; `FLOCK`; `DELEG`; `LEASE` | | [`file.lock.mode`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` | | [`file.lock.type`](/docs/registry/attributes/file.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The [lock type](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html) | `read` | | [`system.device`](/docs/registry/attributes/system.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | OS-specific identifier for the device where the file resides. | `08:01` |