Skip to content

Commit 605123a

Browse files
authored
[chore] add guidelines for telemetry stability levels (#14280)
<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue. Ex. Adding a feature - Explain what this achieves.--> #### Description This PR adds a guideline section about the stability levels the produced components' telemetry should follow. <!-- Issue number if applicable --> #### Link to tracking issue Related to open-telemetry/opentelemetry.io#8558 and #13910. --------- Signed-off-by: ChrsMark <[email protected]>
1 parent 0253d53 commit 605123a

File tree

2 files changed

+38
-0
lines changed

2 files changed

+38
-0
lines changed

docs/coding-guidelines.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,40 @@ SemConv approvers.
353353
At their discretion, the code owners may choose to block the component’s implementation PR until the related
354354
Semantic Conventions changes are completed.
355355

356+
## Telemetry Stability Levels
357+
358+
### Metrics
359+
360+
Metrics emitted by Collector scrapers/receivers (e.g. `system.cpu.time`) follow the same stability levels
361+
as the Collector's internal metrics (e.g. `otelcol_process_cpu_seconds`), as documented in
362+
[Internal Telemetry Stability](https://opentelemetry.io/docs/collector/internal-telemetry/#metrics).
363+
364+
In particular, for beta and stable levels the following guidelines apply:
365+
366+
#### Beta stability level
367+
368+
It is highly encouraged that metrics in beta stage
369+
are also defined as Semantic Conventions based on the [Semantic Conventions compatibility](#semantic-conventions-compatibility),
370+
ensuring cross-project consistency.
371+
372+
#### Stable stability level
373+
374+
Before promoting a metric to stable, it should be discussed whether it needs to
375+
be defined as a Semantic Convention, following the [Semantic Conventions compatibility](#semantic-conventions-compatibility).
376+
Promoting a metric to stable without it being a Semantic Convention involves
377+
the risk of potential divergence within OpenTelemetry's projects.
378+
For example, a stable metric in the Collector might be introduced in a slightly
379+
different way in another OpenTelemetry project in the future, or it might be proposed
380+
as a Semantic Convention in the future.
381+
In case of such divergence, a stable Collector metric won't be allowed to
382+
change, and if wider alignment is needed, the metric should be deprecated and
383+
removed in order to come into alignment with the Semantic Conventions.
384+
Consequently, the Collector's maintainers and components' code owners should
385+
acknowledge that risk before marking a metric as stable without it being a
386+
stable Semantic Convention and should provide justification for the decision. In
387+
any case, [Semantic Conventions' guidelines](https://opentelemetry.io/docs/specs/semconv/how-to-write-conventions/)
388+
should be advised when metrics are defined within the Collector directly.
389+
356390
### Testing Library Recommendations
357391

358392
To keep testing practices consistent across the project, it is advised to use these libraries under

docs/scraping-receivers.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,10 @@ Nevertheless, metrics that are emitted by default MUST be always kept up-to-date
7979
monitored system. Given that, occasional breaking changes in the emitted metrics are expected even in the stable
8080
receivers. Any breaking change MUST be applied following [the deprecation process](#changing-the-emitted-metrics).
8181

82+
## Stability levels for metrics and attributes
83+
84+
See [Collector's Telemetry Stability levels](./coding-guidelines.md#telemetry-stability-levels)
85+
8286
## Changing the emitted metrics
8387

8488
Some changes are not considered breaking and can be applied to metrics emitted by scraping receivers of any

0 commit comments

Comments
 (0)