Skip to content
Open
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/rename_system_linux.yaml
Original file line number Diff line number Diff line change
@@ -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:
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,6 @@ body:
- area:ios
- area:jvm
- area:k8s
- area:linux
- area:log
- area:mainframe
- area:messaging
Expand Down
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/change_proposal.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@ body:
- area:ios
- area:jvm
- area:k8s
- area:linux
- area:log
- area:mainframe
- area:messaging
Expand Down
1 change: 0 additions & 1 deletion .github/ISSUE_TEMPLATE/new-conventions.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,6 @@ body:
- area:ios
- area:jvm
- area:k8s
- area:linux
- area:log
- area:mainframe
- area:messaging
Expand Down
2 changes: 1 addition & 1 deletion docs/general/naming.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}`. <!-- TODO: document why-->

- [RPC](/docs/rpc/README.md) and [messaging](/docs/messaging/README.md) semantic
Expand Down
6 changes: 3 additions & 3 deletions docs/registry/attributes/linux.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@

# Linux

## Linux Memory Attributes
## Deprecated Linux Attributes

Describes Linux Memory attributes
Deprecated Linux attributes.

| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="linux-memory-slab-state" href="#linux-memory-slab-state">`linux.memory.slab.state`</a> | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="linux-memory-slab-state" href="#linux-memory-slab-state">`linux.memory.slab.state`</a> | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `system.memory.linux.slab.state`. |

---

Expand Down
10 changes: 10 additions & 0 deletions docs/registry/attributes/system.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,20 @@ Describes System Memory attributes

| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="system-memory-linux-slab-state" href="#system-memory-linux-slab-state">`system.memory.linux.slab.state`</a> | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="system-memory-state" href="#system-memory-state">`system.memory.state`</a> | string | The memory state | `free`; `cached` | ![Development](https://img.shields.io/badge/-development-blue) |

---

`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 |
Expand Down
26 changes: 13 additions & 13 deletions docs/system/system-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<!-- tocstop -->

Expand Down Expand Up @@ -1149,7 +1149,7 @@ This metric is [recommended][MetricRecommended].
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## `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
Expand Down Expand Up @@ -1181,9 +1181,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`

<!-- semconv metric.system.linux.memory.available -->
<!-- semconv metric.system.memory.linux.available -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
Expand All @@ -1192,7 +1192,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.
Expand All @@ -1205,11 +1205,11 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### Metric: `system.linux.memory.slab.usage`
### Metric: `system.memory.linux.slab.usage`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.system.linux.memory.slab.usage -->
<!-- semconv metric.system.memory.linux.slab.usage -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
Expand All @@ -1218,19 +1218,19 @@ 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).

| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`linux.memory.slab.state`](/docs/registry/attributes/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`system.memory.linux.slab.state`](/docs/registry/attributes/system.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |

---

`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 |
|---|---|---|
Expand Down
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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
34 changes: 34 additions & 0 deletions model/system/deprecated/metrics-deprecated.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
14 changes: 7 additions & 7 deletions model/system/metrics.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Copy link
Member

@lmolkova lmolkova Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think https://github.com/open-telemetry/semantic-conventions/blob/main/docs/non-normative/groups/system/design-philosophy.md#operating-system-in-names talks about root namespace, is there a need or benefit in renaming system.linux.memory.slab.usage to system.memory.linux.slab.usage ?

In the new version, linux looks like a property of memory and separates actual slab.usage property. In the old version it feels in the right place - it's a property of a system.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might need to rephrase it, but I think instead of "root namespace" what we meant is {area}. The way we think a user interacts with system metrics is by first looking into the area of interest (e.g. memory consumption alert) and then (if needed), looking to the OS more fine-grained metrics for that area.

If we just apply the rule to root namespaces, we could end up having a mix of unordered metrics like memory.linux.* and system.linux.memory.*.

cc @braydonk

Copy link
Member

@lmolkova lmolkova Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not going to block on this, but I'm still raising concern. It seems random where OS name is included and it affects name readability

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Semconv SIG discussion: could you please update the guidance based on this discussion? thanks!

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
12 changes: 12 additions & 0 deletions model/system/registry.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading