[k8s] Improve *.cpu.usage description

[ChrsMark]

Related to #2418

Changes

After the relevant discussions at #2418, the @open-telemetry/semconv-k8s-approvers group decided to switch the implementation detail of how the *.cpu.usage metrics are populated.

Instead of deriving them directly from the Kubelet Stat's API and the UsageNanoCores in particular, the group decided that populating this metric on the fly, using the usageCores = (cpuTimeEnd - cpuTimeStart) / elapsedSeconds formula, is more accurate. Calculating this metric using the actual scraping interval is more accurate and correct than relying on the fixed interval based on which the Kubelet derived metric is calculated (as proved at #2418 (comment)).

This is also in alignment with the description of:

• process.cpu.utilization
• system.cpu.utilization

(Note that utilization = usage / limit)

The implementation switch is already in place behind a feature gate pair, introduced in the Collector by open-telemetry/opentelemetry-collector-contrib#49499.

This change is not a breaking change since the formula and concept for these metrics remain the same, with only the implementation detail being changed.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Links to prototypes or existing instrumentations (when adding or changing conventions)
• Disclose AI usage, see OTel GenAI policy:
  • no AI used
  • AI-assisted
  • bulk AI-generated
• I have the experience and knowledge necessary to understand, review, and validate all content in this PR.¹

/cc @open-telemetry/semconv-k8s-approvers @jmmcorreia

Footnotes

1. Yes, I can answer maintainer questions about the content of this PR without using AI. ↩

[opentelemetry-pr-dashboard]

Pull request dashboard status

Status last refreshed: 2026-07-25 10:12:41 UTC.

• Waiting on: Reviewers
• Next step: Review the latest changes.

This automated status or its linked feedback items may be incorrect. If something looks wrong, please report it with the result you expected.