diff --git a/.chloggen/rename_system_linux.yaml b/.chloggen/rename_system_linux.yaml new file mode 100755 index 0000000000..87d0a8ee8e --- /dev/null +++ b/.chloggen/rename_system_linux.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: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: system, linux + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Rename `*.linux.memory` metrics and attributes to `*.memory.linux` + +# 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: [1661] + +# (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/.github/CODEOWNERS b/.github/CODEOWNERS index a4a60146db..636d070396 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -52,6 +52,7 @@ /model/cpu/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/disk/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/host/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers +/model/linux/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers # /model/network/ is defined in HTTP section /model/os/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers /model/process/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-system-approvers @open-telemetry/semconv-security-approvers diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index a187ceb14d..bc47e17aed 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -65,7 +65,6 @@ body: - area:ios - area:jvm - area:k8s - - area:linux - area:log - area:mainframe - area:messaging diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 7cbe913ab9..22ae1f480c 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -57,7 +57,6 @@ body: - area:ios - area:jvm - area:k8s - - area:linux - area:log - area:mainframe - area:messaging diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 8955a43f71..b5ba619910 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -68,7 +68,6 @@ body: - area:ios - area:jvm - area:k8s - - area:linux - area:log - area:mainframe - area:messaging diff --git a/AREAS.md b/AREAS.md index 424978f9d0..127c5bae73 100644 --- a/AREAS.md +++ b/AREAS.md @@ -27,7 +27,7 @@ their owners, related project (and project board) as well as its current status. | Name | Owners | Project | Board | Labels | Status | Notes | |------|--------|---------|-------|-------|--------|-------| -| Semantic Conventions: System | [semconv-system-approvers](https://github.com/orgs/open-telemetry/teams/semconv-system-approvers) | https://github.com/open-telemetry/community/blob/main/projects/system-semconv.md | https://github.com/orgs/open-telemetry/projects/55 | `area:system`, `area:host`, `area:process`, `area:nfs`, `area:os`, `area:cpu`, `area:disk`, `area:network` | `accepting_contributions`, `active` | The SIG is looking for contributions! | +| Semantic Conventions: System | [semconv-system-approvers](https://github.com/orgs/open-telemetry/teams/semconv-system-approvers) | https://github.com/open-telemetry/community/blob/main/projects/system-semconv.md | https://github.com/orgs/open-telemetry/projects/55 | `area:system`, `area:host`, `area:process`, `area:nfs`, `area:os`, `area:cpu`, `area:disk`, `area:network`, `area:linux` | `accepting_contributions`, `active` | The SIG is looking for contributions! | | Semantic Conventions: K8s | [semconv-k8s-approvers](https://github.com/orgs/open-telemetry/teams/semconv-k8s-approvers) | https://github.com/open-telemetry/community/blob/main/projects/k8s-semconv.md | https://github.com/orgs/open-telemetry/projects/114 | `area:k8s` | `accepting_contributions`, `active` | The SIG is looking for contributions! | | Semantic Conventions: GenAI | [semconv-genai-approvers](https://github.com/orgs/open-telemetry/teams/semconv-genai-approvers) | https://github.com/open-telemetry/community/blob/main/projects/gen-ai.md | https://github.com/orgs/open-telemetry/projects/82 | `area:gen-ai`, `area:openai` | `accepting_contributions`, `active` | The SIG is looking for contributions! | | Semantic Conventions: CI/CD | [semconv-cicd-approvers](https://github.com/orgs/open-telemetry/teams/semconv-cicd-approvers) | https://github.com/open-telemetry/community/blob/main/projects/ci-cd.md | https://github.com/orgs/open-telemetry/projects/79 | `area:cicd`, `area:artifact`, `area:deployment`, `area:test`, `area:vcs` | `accepting_contributions`, `active` | The SIG is looking for contributions! | diff --git a/areas.yaml b/areas.yaml index a2ca0801b6..d2055f5762 100644 --- a/areas.yaml +++ b/areas.yaml @@ -14,6 +14,7 @@ areas: - area:cpu - area:disk - area:network + - area:linux status: - accepting_contributions - active diff --git a/docs/general/naming.md b/docs/general/naming.md index 0094813d81..3932ce4877 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -426,7 +426,7 @@ attribute use the same system name (`azure.cosmosdb`). ### Known exceptions - Operational system and process-related attributes and metrics [follow a - pattern](/docs/system/system-metrics.md#systemos---os-specific-system-metrics) + pattern](/docs/system/system-metrics.md#systemmemoryos---os-specific-system-memory-metrics) of `system.{os}` and `process.{os}`. - [RPC](/docs/rpc/README.md) and [messaging](/docs/messaging/README.md) semantic diff --git a/docs/non-normative/groups/system/design-philosophy.md b/docs/non-normative/groups/system/design-philosophy.md index fd6861be42..a5a51774f6 100644 --- a/docs/non-normative/groups/system/design-philosophy.md +++ b/docs/non-normative/groups/system/design-philosophy.md @@ -213,7 +213,7 @@ The `brief` field should explain what the metric/attribute is, and if the explanation of a value is simple (i.e. simply surfacing a value from a common source like `procfs`) then the explanation of what the value should be can go in the brief. If the value needs some calculation explanation and justification, -the information should be moved to the `note` field. +the information should be moved to the `note` field. For enum values, it is often the case that the intention of these values is obvious given whatever `brief` was provided for the attribute as a whole. A brief can be included in a scenario where we have had to make some choice on the @@ -277,6 +277,7 @@ down with more specificity. Relevant discussions: [\#1255](https://github.com/open-telemetry/semantic-conventions/issues/1255), [\#1364](https://github.com/open-telemetry/semantic-conventions/pull/1364#discussion_r1852465994) +[\#2984](https://github.com/open-telemetry/semantic-conventions/pull/2984#discussion_r2466369361) Monitoring operating systems is an old practice, and there are numerous heavily differing approaches within different platforms. There are lots of metrics, even @@ -289,7 +290,7 @@ Thus we have decided that any instrumentation that is: 1. Specific to a particular operating system 2. Not meant to be part of what we consider our most important general use cases -will have the Operating System name as part of the namespace. +will include the Operating System name as part of the namespace. For example, there may be `process.linux`, `process.windows`, or `process.posix` names for metrics and attributes. We will not have root `linux.*`, `windows.*`, @@ -300,4 +301,6 @@ had OS root namespaces, different sources like `system`, `process`, etc. could get very tangled within each OS namespace, defeating the intended design philosophy. +However, to clarify — when we refer to avoiding OS names at the “root namespace” level, we also mean avoiding them at the area level. The OS name should appear after the area of concern (such as `system.memory.linux.*`), not before it. This ensures that users can first navigate by functional area (e.g. memory, CPU, network) and then, if necessary, drill down into OS-specific variants within that area. + [use cases doc]: ./use-cases.md diff --git a/docs/registry/attributes/linux.md b/docs/registry/attributes/linux.md index 5848ad3226..5cd1f38873 100644 --- a/docs/registry/attributes/linux.md +++ b/docs/registry/attributes/linux.md @@ -3,15 +3,15 @@ # Linux -## Linux Memory Attributes +## Deprecated Linux Attributes -Describes Linux Memory attributes +Deprecated Linux attributes. **Attributes:** | Key | Stability | Value Type | Description | Example Values | |---|---|---|---|---| -| `linux.memory.slab.state` | ![Development](https://img.shields.io/badge/-development-blue) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | +| `linux.memory.slab.state` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `system.memory.linux.slab.state`. | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | --- diff --git a/docs/registry/attributes/system.md b/docs/registry/attributes/system.md index 44534b304c..403b4adf22 100644 --- a/docs/registry/attributes/system.md +++ b/docs/registry/attributes/system.md @@ -63,10 +63,20 @@ Describes System Memory attributes | Key | Stability | Value Type | Description | Example Values | |---|---|---|---|---| +| `system.memory.linux.slab.state` | ![Development](https://img.shields.io/badge/-development-blue) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | | `system.memory.state` | ![Development](https://img.shields.io/badge/-development-blue) | string | The memory state | `free`; `cached` | --- +`system.memory.linux.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 | ![Development](https://img.shields.io/badge/-development-blue) | +| `unreclaimable` | unreclaimable | ![Development](https://img.shields.io/badge/-development-blue) | + +--- + `system.memory.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 | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index e67d79f28b..c13a1b0cf4 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -57,9 +57,9 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam - [Aggregate system process metrics](#aggregate-system-process-metrics) - [Metric: `system.process.count`](#metric-systemprocesscount) - [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) +- [`system.memory.{os}.` - OS Specific System Memory Metrics](#systemmemoryos---os-specific-system-memory-metrics) + - [Metric: `system.memory.linux.available`](#metric-systemmemorylinuxavailable) + - [Metric: `system.memory.linux.slab.usage`](#metric-systemmemorylinuxslabusage) @@ -1197,7 +1197,7 @@ This metric is [recommended][MetricRecommended]. -## `system.{os}.` - OS Specific System Metrics +## `system.memory.{os}.` - OS Specific System Memory Metrics Instrument names for system level metrics that have different and conflicting meaning across multiple OSes should be prefixed with `system.{os}.` and @@ -1229,9 +1229,9 @@ an `{os}` prefix to split this metric across OSes. [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended [MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in -### Metric: `system.linux.memory.available` +### Metric: `system.memory.linux.available` - + @@ -1240,7 +1240,7 @@ an `{os}` prefix to split this metric across OSes. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `system.linux.memory.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | +| `system.memory.linux.available` | UpDownCounter | `By` | An estimate of how much memory is available for starting new applications, without causing swapping. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | **[1]:** This is an alternative to `system.memory.usage` metric with `state=free`. Linux starting from 3.14 exports "available" memory. It takes "free" memory as a baseline, and then factors in kernel-specific values. @@ -1253,11 +1253,11 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5 -### Metric: `system.linux.memory.slab.usage` +### Metric: `system.memory.linux.slab.usage` This metric is [recommended][MetricRecommended]. - + @@ -1266,9 +1266,9 @@ This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | -| `system.linux.memory.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | +| `system.memory.linux.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) | -**[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. +**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `memory.linux.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). @@ -1276,11 +1276,11 @@ See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding- | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |---|---|---|---|---|---| -| [`linux.memory.slab.state`](/docs/registry/attributes/linux.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | +| [`system.memory.linux.slab.state`](/docs/registry/attributes/system.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | --- -`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. +`system.memory.linux.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 | |---|---|---| diff --git a/model/linux/registry.yaml b/model/linux/registry-deprecated.yaml similarity index 67% rename from model/linux/registry.yaml rename to model/linux/registry-deprecated.yaml index 6b585719b3..58db637dfb 100644 --- a/model/linux/registry.yaml +++ b/model/linux/registry-deprecated.yaml @@ -1,9 +1,8 @@ groups: - # linux.memory.* attribute group - - id: registry.linux.memory + - id: registry.linux.deprecated type: attribute_group - display_name: Linux Memory Attributes - brief: "Describes Linux Memory attributes" + display_name: Deprecated Linux Attributes + brief: "Deprecated Linux attributes." attributes: - id: linux.memory.slab.state type: @@ -17,3 +16,6 @@ groups: stability: development brief: "The Linux Slab memory state" examples: ["reclaimable", "unreclaimable"] + deprecated: + reason: renamed + renamed_to: system.memory.linux.slab.state diff --git a/model/system/deprecated/metrics-deprecated.yaml b/model/system/deprecated/metrics-deprecated.yaml index b58ef85bca..4787116524 100644 --- a/model/system/deprecated/metrics-deprecated.yaml +++ b/model/system/deprecated/metrics-deprecated.yaml @@ -58,3 +58,37 @@ groups: - ref: network.io.direction entity_associations: - host + + - id: metric.system.linux.memory.available + type: metric + metric_name: system.linux.memory.available + annotations: + code_generation: + metric_value_type: int + stability: development + deprecated: + reason: renamed + renamed_to: system.memory.linux.available + brief: The number of packets transferred. + instrument: counter + unit: "{packet}" + entity_associations: + - host + + - id: metric.system.linux.memory.slab.usage + type: metric + metric_name: system.linux.memory.slab.usage + annotations: + code_generation: + metric_value_type: int + stability: development + deprecated: + reason: renamed + renamed_to: system.memory.linux.slab.usage + brief: The number of packets transferred. + instrument: counter + unit: "{packet}" + attributes: + - ref: linux.memory.slab.state + entity_associations: + - host diff --git a/model/system/metrics.yaml b/model/system/metrics.yaml index f7b04225e1..7a13fdb91a 100644 --- a/model/system/metrics.yaml +++ b/model/system/metrics.yaml @@ -524,10 +524,10 @@ groups: entity_associations: - host - # system.linux.* metrics - - id: metric.system.linux.memory.available + # system.memory.linux.* metrics + - id: metric.system.memory.linux.available type: metric - metric_name: system.linux.memory.available + metric_name: system.memory.linux.available annotations: code_generation: metric_value_type: int @@ -545,21 +545,21 @@ groups: entity_associations: - host - - id: metric.system.linux.memory.slab.usage + - id: metric.system.memory.linux.slab.usage type: metric - metric_name: system.linux.memory.slab.usage + metric_name: system.memory.linux.slab.usage annotations: code_generation: metric_value_type: int stability: development 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. + The sum over the `reclaimable` and `unreclaimable` state values in `memory.linux.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 + - ref: system.memory.linux.slab.state entity_associations: - host diff --git a/model/system/registry.yaml b/model/system/registry.yaml index 435be45644..fab5dea6c9 100644 --- a/model/system/registry.yaml +++ b/model/system/registry.yaml @@ -47,6 +47,18 @@ groups: stability: development brief: "The memory state" examples: ["free", "cached"] + - id: system.memory.linux.slab.state + type: + members: + - id: reclaimable + value: 'reclaimable' + stability: development + - id: unreclaimable + value: 'unreclaimable' + stability: development + stability: development + brief: "The Linux Slab memory state" + examples: ["reclaimable", "unreclaimable"] # system.paging.* attribute group - id: registry.system.paging type: attribute_group