Skip to content

Require telemetry stability in stable artifacts #18789

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trask merged 1 commit into from
May 19, 2026
Merged

Require telemetry stability in stable artifacts #18789

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions VERSIONING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,28 @@
# OpenTelemetry Java Instrumentation Versioning

## Compatibility requirements
## Compatibility and telemetry stability requirements

Artifacts in this repository follow the same compatibility requirements described in
<https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#compatibility-requirements>
.
Artifacts in this repository follow the compatibility requirements described in the
[OpenTelemetry Java versioning document](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#compatibility-requirements)
and the OpenTelemetry specification
[versioning and stability document](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md).

EXCEPT for the following incompatible changes which are allowed in stable artifacts in this
repository:
For any stable artifact in this repository, public portions of the artifact must remain backward
compatible, including public Java APIs and user-facing configuration. Backward-incompatible changes
to stable artifacts are only allowed when incrementing the `MAJOR` version number, except for the
following configuration changes:

- Changes to configuration properties that contain the word `experimental`
- Changes to configuration properties under the namespace `otel.javaagent.testing`
- Changes to configuration properties that contain the word `experimental`.
- Changes to configuration properties under the namespace `otel.javaagent.testing`.

This means that:

- Changes to configuration properties (other than those that contain the word `experimental`
or are under the namespace `otel.javaagent.testing`) will be considered breaking changes
(unless they only affect telemetry produced by instrumentation)
- Changes to all other configuration properties are considered breaking changes.
- Changes to telemetry produced by stable instrumentation artifacts in this repository are
considered breaking unless they are allowed by the OpenTelemetry specification
[Semantic Conventions Stability](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md#semantic-conventions-stability)
requirements. This repository uses those requirements to define breaking and non-breaking
telemetry changes for stable instrumentation artifacts.

## Stable vs alpha

Expand Down
Loading