Add support for filesystem locks and their metrics

.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:

docs/registry/attributes/file.md

@@ -3,6 +3,9 @@
 
 # File
 
+- [File Attributes](#file-attributes)
+- [File lock](#file-lock)
+
 ## 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 lock
+
+These attributes may be used for any filesystem lock or related operation
+
+**Attributes:**
+
+| Key | Stability | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- |
+| <a id="file-lock-mechanism" href="#file-lock-mechanism">`file.lock.mechanism`</a> | ![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` |
+| <a id="file-lock-mode" href="#file-lock-mode">`file.lock.mode`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Mode of lock or operation | `ADVISORY`; `MANDATORY`; `BREAKING`; `ACTIVE`; `BREAKER` |
+| <a id="file-lock-type" href="#file-lock-type">`file.lock.type`</a> | ![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) |

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)
@@ -827,6 +828,39 @@ This metric is [opt-in][MetricOptIn].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
+### Metric: `system.filesystem.lock.count`
+
+<!-- semconv metric.system.filesystem.lock.count -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+| 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) |
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
 ## Network metrics
 
 **Description:** System level network metrics captured under the namespace `system.network`.

model/file/registry.yaml

@@ -137,3 +137,32 @@ 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 lock
+    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.mechanism
+        type: string
+        brief: "The lock [mechanism](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html)"
+        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"]

model/system/metrics.yaml

@@ -384,6 +384,26 @@ groups:
     entity_associations:
       - host
 
+  - id: metric.system.filesystem.lock.count
+    type: metric
+    metric_name: system.filesystem.lock.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 file resides.
+        examples: ["08:01"]
+      - ref: file.lock.type
+      - ref: file.lock.mechanism
+      - ref: file.lock.mode
+    entity_associations:
+      - host
+
   # system.network.* metrics
   - id: metric.system.network.packet.dropped
     type: metric