Add per-metric stability guidelines #5487
Conversation
Codecov Report
@@ Coverage Diff @@
## main #5487 +/- ##
=======================================
Coverage 90.79% 90.79%
=======================================
Files 193 193
Lines 11430 11430
=======================================
Hits 10378 10378
Misses 830 830
Partials 222 222 Continue to review full report at Codecov.
|
README.md
Outdated
|
|
||
| The component is planned to be removed in a future version and no further support will be provided. Note that new issues will likely not be worked on. When a component enters "deprecated" mode, it is expected to exist for at least two minor releases. See the component's readme file for more details on when a component will cease to exist. | ||
|
|
||
| ### Metric stability levels | ||
|
|
||
| Receivers that produce metrics should declare a stability level for each metric. A for each metric may not exceed the The status for each metric should be listed in the receiver's `documentation.md` file according to the following definitions: |
There was a problem hiding this comment.
A for each metric something sounds off here.
| ### Stability level progression | ||
|
|
||
| Comonents and metric stability levels should progress according to the following guidelines: | ||
| - A component that produces metrics should produce at least one metric of the same stability level. For example, a Stable component should produce at least one Stable metric. |
There was a problem hiding this comment.
Why? If we did not have metrics in a stable component, and start adding them now? How do I get to stable directly?
There was a problem hiding this comment.
My intention here is to address primarily how it "should" be. Then we would take steps to get there.
As to the reasoning here, this just seems necessary in order to give meaning to the component status. I would question whether a scraper can be stable if it produces no stable metrics.
There was a problem hiding this comment.
:))) Is this about own "observability" metrics, or about "scrapers" like components :))) I feel that I was just confusing everything
There was a problem hiding this comment.
I was mostly trying to address scrapers, but didn't use the term because I'm not sure it's a user-facing term. (I said receivers that produce metrics instead, but maybe this isn't specific enough.)
That said, I think all of this would apply to own telemetry as well, with the exception of this line.
There was a problem hiding this comment.
How is this different than "receiver that produce logs" or "spans" should we actually call this "telemetry"?
I would probably have a different term for "own observability telemetry" vs "telemetry on behalf of others" :))
There was a problem hiding this comment.
I would probably have a different term for "own observability telemetry" vs "telemetry on behalf of others" :))
Makes sense. I think "own telemetry" would be clear and is already used elsewhere (eg OpAMP). Perhaps "scraped telemetry" then for the other term.
How is this different than "receiver that produce logs" or "spans" should we actually call this "telemetry"?
The way I see it is that metrics have named instances, each of which has its own detailed data model. Maybe I'm overlooking something, but I don't think logs and spans have an equivalent really.
In any case, I can try to organize this PR to leave room for future stability guidelines for other signals, but I only have detailed thoughts for metrics at this point. What do you think of organizing it like this:
## Metric stability levels
### "Own metrics" vs "Scraped metrics"
// TODO describe the difference and give a couple examples
The following levels and guidelines apply to "own metrics" and "scraped metrics", except where otherwise noted.
...
### Scraped metrics
Receivers whose sole purpose is to scrape metrics (ie. "scrapers") should produce at least one metric of the same stability level. For example, a Stable component should produce at least one Stable metric.
Then if someone can reuse some of these guidelines for logs and/or spans, they can extract them into a "telemetry" header.
|
|
||
| The component is planned to be removed in a future version and no further support will be provided. Note that new issues will likely not be worked on. When a component enters "deprecated" mode, it is expected to exist for at least two minor releases. See the component's readme file for more details on when a component will cease to exist. | ||
|
|
||
| ### Stability level progression |
There was a problem hiding this comment.
Are you allowed to remove a deprecated metric, or disable to save cost (backend cost as well as runtime cost)?
There was a problem hiding this comment.
Thanks for the reminder to incorporate default enabled state as well. I will add considerations for this.
There was a problem hiding this comment.
I've proposed some guidelines for enabled status within each stability level.
|
This PR was marked stale due to lack of activity. It will be closed in 14 days. |
|
|
||
| The component is planned to be removed in a future version and no further support will be provided. Note that new issues will likely not be worked on. When a component enters "deprecated" mode, it is expected to exist for at least two minor releases. See the component's readme file for more details on when a component will cease to exist. | ||
|
|
||
| ### Metric stability levels |
There was a problem hiding this comment.
How about adding a "Since" property, stating the version of the collector the metric started being reported?
There was a problem hiding this comment.
I think that's a great idea.
|
A closely related issue was opened on the spec repo at roughly the same time as this proposal was drafted. I think that issue should be resolved before this moves forward. |
|
This PR was marked stale due to lack of activity. It will be closed in 14 days. |
|
This PR was marked stale due to lack of activity. It will be closed in 14 days. |
|
Closed as inactive. Feel free to reopen if this PR is still being worked on. |
Resolves (contrib)#9963.
Possibly these should be defined in contrib or in a separate file. I'd appreciate feedback on the guidelines themselves as well as appropriate placement in the documentation.