Skip to content

Conversation

@braydonk
Copy link
Contributor

Part of #864

Changes

This PR adds the requirement levels for all attribute refs in the process namespace.

An attribute being marked required is our way of saying that we do not see a reason for the metric to be instrumented without that attribute present; perhaps there might be uses for aggregating over a particular attribute at query time, but at collection time we expect the attributes to always be produced.

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

Merge requirement checklist

  • CONTRIBUTING.md guidelines followed.
  • Change log entry added, according to the guidelines in When to add a changelog entry.
    • If your PR does not need a change log, start the PR title with [chore]
  • [N/A] Links to the prototypes or existing instrumentations (when adding or changing conventions)

@braydonk braydonk requested review from a team as code owners November 21, 2025 19:55
@braydonk braydonk changed the title [process] Add [process] Add requirement levels to attribute refs Nov 21, 2025
@braydonk braydonk requested a review from a team as a code owner November 21, 2025 19:57
@github-actions github-actions bot added enhancement New feature or request area:process labels Nov 21, 2025
| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/registry/attributes/cpu.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A process SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` |
| [`cpu.mode`](/docs/registry/attributes/cpu.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | A process SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` |
Copy link
Member

Choose a reason for hiding this comment

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

Given the description (data points with no mode labels, or only data points with mode labels.), should this be conditionally required?

Copy link
Contributor

Choose a reason for hiding this comment

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

Does it make sense to aggregate process.cpu.time over cpu.mode (data points with no mode labels)? I think that should be equal to the process.uptime metric, making the aggregation not recommended (attribute required)?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

So I actually don't know if I agree with the brief here; I'm not sure at what point we would ever recommend recording CPU times without a cpu mode. I don't think we have any unambiguous way to report that. A process.cpu.time metric without the mode in my eyes could be one of two things:

  1. Sum of all states, which is equivalent to all elapsed wall clock seconds (aka equivalent to process.uptime as @rogercoll mentioned)
  2. Something like user + system with wait state ignored

1 is generally not useful and I think we would recommend against doing it as it could be easily misinterpreted; a dashboard interpreting a "cpu time" metric that is aggregated in this way could make it look like a process is literally operating on a CPU at all times.

I could see 2 being useful somehow.

The problem then is the ambiguity of these two scenarios; a process.cpu.time metric reported without a cpu.mode has no way to encode which of these 2 versions of the metric being reported are actually being used. The way to disambiguate a scenario that allows the second scenario to exist would just be to report a cpu.mode attribute, defeating the purpose of ever reporting without the attribute. We could try and write some kind of guidance that says if you report without an attribute then what you mean is all non-wait time of the process, but that also has usability concerns because if a process is truly using all wall clock seconds to operate on the CPU, it is much easier to know unambiguously that this is the case if you also report a wait state with a value of 0.
Also in spite of all of this, scenario 2 is better served by a query-time aggregation anyway; if instrumentation aggregated all non-wait states at collection time you'd never be able to split that out again. (this is a similar scenario to utilization metrics erasing important time information because of collection-time aggregation).

Hopefully my rant is clear enough. All of this is to say that I believe the attribute should remain required, and we should adjust the brief to not suggest that we ever want this metric reported without a cpu.mode. How does that sound @open-telemetry/semconv-system-approvers ?

@lmolkova lmolkova moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Nov 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:process enhancement New feature or request

Projects

Status: Awaiting codeowners approval

Development

Successfully merging this pull request may close these issues.

3 participants