-
Notifications
You must be signed in to change notification settings - Fork 282
[process] Add requirement levels to attribute refs #3107
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
| | 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) |  | `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) |  | `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` | |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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)?
There was a problem hiding this comment.
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:
- Sum of all states, which is equivalent to all elapsed wall clock seconds (aka equivalent to
process.uptimeas @rogercoll mentioned) - Something like
user+systemwithwaitstate 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 ?
Part of #864
Changes
This PR adds the requirement levels for all attribute refs in the
processnamespace.An attribute being marked
requiredis 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
[chore]