Tune collector telemetry stability levels to match semconv #8558
Conversation
ChrsMark
force-pushed
the
tune_collector_stability_levels
branch
from
01a6325 to
f16885a
Compare
otelbot-docs
bot
requested review from
a team and
atoulme
and removed request for
a team
| > Metric in `development` → `alpha` Metric → `beta` Metric → `stable` Metric → | ||
| > Deprecated metric → Deleted metric |
There was a problem hiding this comment.
Why is the lifecycle written in this way?
`stable` metric → deprecated metric → deleted metric
I realize this is not new to this PR, but I don't understand why we're making it seem like there's a normal progression from stable to deprecated.
There was a problem hiding this comment.
Hmm I see your point. Also I think metrics can get deprecated from other levels too, i.e. beta-> deprecated. In that case maybe we need to split these 2 "states" into a different section?
`development` metric → `alpha` Metric → `beta` Metric → `stable` Metric
If a metrics needs to be remove it goes through the following stages:
development/alpha/beta/stable metric -> deprecated metric → deleted metric
There was a problem hiding this comment.
We could have a mermaid diagram like https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#moving-between-stability-levels
ChrsMark
force-pushed
the
tune_collector_stability_levels
branch
from
b677037 to
1099be7
Compare
|
I have added an explicit note about suggesting working with Semantic Convention us much as possible: cbe1ce6 This is coming from open-telemetry/opentelemetry-collector#13910 (comment), but I'm happy to hear what do think about this in general. |
|
/fix:refcache |
|
ℹ️ |
ChrsMark
force-pushed
the
tune_collector_stability_levels
branch
2 times, most recently
from
169842e to
cbe1ce6
Compare
| Before promoting a metric to stable, it should be discussed whether it needs to | ||
| be defined as a Semantic Convention, following the suggestion from the | ||
| [Collector guidelines][collectorSemConvGuidelines]. Promoting a metric to stable | ||
| without it being a Semantic Convention involves the risk of potential divergence | ||
| within OpenTelemetry's projects. For example, a stable metric in the Collector | ||
| might be introduced in a slightly different way in another OpenTelemetry project | ||
| in the future, or it might be proposed as a Semantic Convention in the future. | ||
| In case of such divergence, a stable Collector metric won't be allowed to | ||
| change, and if wider alignment is needed, the metric should be deprecated and | ||
| removed in order to come into alignment with the Semantic Conventions. | ||
| Consequently, the Collector's maintainers and components' code owners should | ||
| acknowledge that risk before marking a metric as stable without it being a | ||
| stable Semantic Convention and should provide justification for the decision. In | ||
| any case, [Semantic Conventions' guidelines][semConvGuidelines] should be | ||
| advised when metrics are defined within the Collector directly. |
There was a problem hiding this comment.
I think it is good to have this note somewhere, but this doesn't feel like the right place for it. To me, this document is focused on end-users and should be written with them as a target audience, while this paragraph reads as something for Collector developers
There was a problem hiding this comment.
Fair point. Would that better fit in a section bellow https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/coding-guidelines.md#semantic-conventions-compatibility maybe?
There was a problem hiding this comment.
Yeah, I think that would be a good place for it
ChrsMark
force-pushed
the
tune_collector_stability_levels
branch
from
cbe1ce6 to
448398e
Compare
|
I would also like to request a review from @codeboten since we extensively discussed these changes at open-telemetry/opentelemetry-collector#13910 :). |
ChrsMark
force-pushed
the
tune_collector_stability_levels
branch
from
448398e to
10073a6
Compare
🎁 |
Signed-off-by: ChrsMark <[email protected]>
ChrsMark
force-pushed
the
tune_collector_stability_levels
branch
from
10073a6 to
3c6a98b
Compare
6 participants
contribution guidelines,
including the First-time contributing? note.
the
Generative AI Contribution Policy.
This PR tunes the docs according to the first point of open-telemetry/opentelemetry-collector#13910 (comment):
@open-telemetry/collector-approvers @open-telemetry/collector-contrib-approvers please review.