docs(byoo): document preservation of upstream metric semantics
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 218
- Forks
- 72
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 427
Description
Report needed documentation
Report needed documentation
Document the BYOO telemetry compatibility policy for upstream metrics. The documentation should explain that NVCF preserves upstream metric semantics instead of modifying metrics to retain a historical local shape.
This policy is needed because valid metrics were excluded when the OpenTelemetry Collector exposed otelcol_* counter metrics without the _total suffix and cAdvisor emitted pod-sandbox series with container="POD". The behavior was corrected in #693, but the compatibility policy is not documented for future configuration and validation changes.
Describe the documentation you'd like
Add user-facing or contributor-facing guidance in the appropriate BYOO telemetry documentation that:
- Preserves upstream metric names, types, labels, and label values as emitted.
- Does not rename, filter, or otherwise modify valid upstream metrics solely to retain a local historical shape.
- Treats upstream OpenTelemetry Collector and cAdvisor metric changes as authoritative unless there is a documented user-facing reason to transform them.
- Updates validation fixtures and metric references when upstream behavior changes.
- Uses the OpenTelemetry Collector counter-name change and cAdvisor
container="POD"series as examples. - Explains how related validation guidance preserves upstream metric semantics.
Steps taken to search for needed documentation
Reviewed #693 and its generated metric-reference updates. The change explains the corrected behavior, but it does not establish the compatibility policy as durable documentation.
By submitting this issue, you agree to follow our code of conduct and our contributing guidelines.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review #693 and its generated metric-reference updates first, then locate the appropriate BYOO telemetry documentation. Done means the documentation states the upstream metric preservation policy, includes the OpenTelemetry Collector and cAdvisor examples, and explains how validation guidance and fixtures should follow upstream changes.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, observability-sre
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100