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/docs/registry/attributes/file.md b/docs/registry/attributes/file.md index 2fbde24ff6..493dfd4eb9 100644 --- a/docs/registry/attributes/file.md +++ b/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 | +| --- | --- | --- | --- | --- | +| `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` | + +--- + +`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/docs/system/system-metrics.md b/docs/system/system-metrics.md index aed6abfe51..9a05fb0002 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) @@ -827,6 +828,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`. diff --git a/model/file/registry.yaml b/model/file/registry.yaml index d66188da47..df33411b8f 100644 --- a/model/file/registry.yaml +++ b/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"] diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index e72dc9a5a9..ad494315ed 100644 --- a/model/system/metrics.yaml +++ b/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