[chore] Non-normative guidance for status metrics by braydonk · Pull Request #2472 · open-telemetry/semantic-conventions

braydonk · 2025-07-03T15:40:08Z

Changes

This PR adds non-normative guidance for designing status metrics. This is a common metric pattern that has confused contributors in the past, so this document exists to clear up some misconceptions and outline a unified design plan.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
[N/A] 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] schema-next.yaml updated with changes to existing conventions.

This PR adds non-normative guidance for designing status metrics. This is a common metric pattern that has confused contributors in the past, so this document exists to clear up some misconceptions and outline a unified design plan.

joaopgrassi

Thank you for putting this together!

joaopgrassi · 2025-07-04T07:11:00Z

This can also close this old issue #199. CC @riverar

riverar · 2025-07-15T19:34:28Z

This can also close this old issue #199. CC @riverar

Can you elaborate on this? I read the document and didn't really come away with any clarity with regards to my very specific desktop app monitoring scenario. Maybe I missed something?

ChrsMark · 2025-08-26T11:53:33Z

Hey @braydonk, any updates on this? It's currently blocking related progress i.e. #2488, so it'd be nice to move this guidance forward.

joaopgrassi · 2025-08-28T15:26:50Z

This can also close this old issue #199. CC @riverar

Can you elaborate on this? I read the document and didn't really come away with any clarity with regards to my very specific desktop app monitoring scenario. Maybe I missed something?

Well, in your original issue you described the need to observe/monitor the state/heartbeat of an app. This now described a state metric which basically can be used to report a boolean state 1/0/on/off using an UpDownCounter.

riverar · 2025-08-28T15:45:16Z

@joaopgrassi Agreed. Took a look at it again this morning with fresh eyes and it makes sense to me. Thank you!

braydonk · 2025-08-28T15:46:49Z

Summer busy-ness and other fires to put out has forced me to push this off for longer than I meant to. I still intend to come back and clean this up based on review comments.

ChrsMark

Thank's for putting this together!

joaopgrassi

non blocking comment

Copilot

Pull Request Overview

This PR introduces non-normative guidance for designing status metrics in the OpenTelemetry semantic conventions. The document aims to clarify common misconceptions and provide a unified design approach for metrics that represent entities in specific states.

Key changes:

Creates a new guidance document defining "status metrics" and their design patterns
Establishes conventions for instrument type, naming, and attribute usage
Provides clarification on when to use entity attributes vs. status metrics

SylvainJuge · 2025-09-23T07:07:06Z

When building "JMX state metrics" in Java instrumentation we took inspiration from the hw.status metric defined in hardware semantic conventions, once this recommendation is merged it would be beneficial to also rename hw.status to hw.state to prevent future inconsistencies.

I am not aware of any other similar status metric elsewhere, but my knowledge is quite limited here so maybe an exhaustive review would be needed to identify other candidates for alignment.

braydonk · 2025-09-23T13:53:16Z

Once this recommendation is merged it would be beneficial to also rename hw.status to hw.state to prevent future inconsistencies.

*.status as the metric name and *.state as the attribute name is actually what is written as the guidance here; hw.status is matching the written guidance here. The upcoming metric process.status will use this as well. Other examples of this metric pattern exist in k8s.* but there is lots of existing verbiage there that is used instead.

SylvainJuge · 2025-09-23T14:33:57Z

*.status as the metric name and *.state as the attribute name is actually what is written as the guidance here; hw.status is matching the written guidance here. The upcoming metric process.status will use this as well. Other examples of this metric pattern exist in k8s.* but there is lots of existing verbiage there that is used instead.

My bad, I should have paid more attention while reading it. The good news is that there is nothing to change then, maybe as a follow-up adding a link from hw.status metric to this recommendation would be beneficial.

[chore] Non-normative guidance for status metrics

e2eee01

This PR adds non-normative guidance for designing status metrics. This is a common metric pattern that has confused contributors in the past, so this document exists to clear up some misconceptions and outline a unified design plan.

braydonk requested review from a team as code owners July 3, 2025 15:40

github-project-automation Bot added this to Semantic Conventions Triage Jul 3, 2025

github-project-automation Bot moved this to Untriaged in Semantic Conventions Triage Jul 3, 2025

generate toc

f17bfde

joaopgrassi reviewed Jul 4, 2025

View reviewed changes

Comment thread docs/non-normative/status-metrics.md Outdated

Comment thread docs/non-normative/status-metrics.md Outdated

braydonk mentioned this pull request Jul 4, 2025

Clarify metrics containing an attribute sharing the same name #2476

Closed

lmolkova reviewed Jul 4, 2025

View reviewed changes

ChrsMark mentioned this pull request Jul 10, 2025

Add k8s.pod.phase and k8s.pod.status.reason metrics #2488

Merged

3 tasks

ChrsMark mentioned this pull request Sep 1, 2025

receiver/k8scluster: add status reason metric open-telemetry/opentelemetry-collector-contrib#42347

Merged

braydonk added 2 commits September 11, 2025 10:11

address review comments

ec07dec

toc generate

75b2dc8

braydonk commented Sep 11, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md

ChrsMark approved these changes Sep 15, 2025

View reviewed changes

joaopgrassi moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Sep 15, 2025

joaopgrassi approved these changes Sep 15, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md Outdated

github-project-automation Bot moved this from Awaiting codeowners approval to Needs More Approval in Semantic Conventions Triage Sep 15, 2025

lmolkova approved these changes Sep 15, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md Outdated

lmolkova requested a review from Copilot September 15, 2025 11:22

Copilot AI reviewed Sep 15, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md Outdated

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md Outdated

address review feedback

5e2b502

kamphaus reviewed Sep 15, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md

jsuereth reviewed Sep 15, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md Outdated

jsuereth reviewed Sep 15, 2025

View reviewed changes

Comment thread docs/non-normative/how-to-write-conventions/status-metrics.md

address review comments

ddf11fd

jsuereth approved these changes Sep 17, 2025

View reviewed changes

lmolkova moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Sep 22, 2025

kamphaus approved these changes Sep 22, 2025

View reviewed changes

github-project-automation Bot moved this from Ready to be Merged to Needs More Approval in Semantic Conventions Triage Sep 22, 2025

kamphaus moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Sep 22, 2025

lmolkova enabled auto-merge September 22, 2025 15:25

trask approved these changes Sep 22, 2025

View reviewed changes

github-project-automation Bot moved this from Ready to be Merged to Needs More Approval in Semantic Conventions Triage Sep 22, 2025

trask mentioned this pull request Sep 22, 2025

Consider state metric conventions open-telemetry/opentelemetry-java-instrumentation#14753

Closed

SylvainJuge approved these changes Sep 23, 2025

View reviewed changes

jsuereth moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Sep 25, 2025

lmolkova added this pull request to the merge queue Sep 29, 2025

Merged via the queue into open-telemetry:main with commit 98de3da Sep 29, 2025
15 checks passed

Conversation

braydonk commented Jul 3, 2025

Changes

Merge requirement checklist

Uh oh!

joaopgrassi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

joaopgrassi commented Jul 4, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

riverar commented Jul 15, 2025

Uh oh!

ChrsMark commented Aug 26, 2025

Uh oh!

joaopgrassi commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

riverar commented Aug 28, 2025

Uh oh!

braydonk commented Aug 28, 2025

Uh oh!

Uh oh!

ChrsMark left a comment

Choose a reason for hiding this comment

Uh oh!

joaopgrassi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SylvainJuge commented Sep 23, 2025

Uh oh!

braydonk commented Sep 23, 2025

Uh oh!

SylvainJuge commented Sep 23, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

joaopgrassi commented Aug 28, 2025 •

edited

Loading