Grafana Alloy backward compatibility

Mon, 30 Mar 2026 15:47:22 +0000

Grafana Alloy backward compatibility

Grafana Alloy follows semantic versioning. Exceptions may arise that require a breaking change without a new major version. Alloy is stable, and we strive to maintain backward compatibility between minor and patch versions.

Documented functionality that’s released as Generally available is covered by backward compatibility, including:

User configuration, including the Alloy configuration syntax, the semantics of the configuration file, and the command-line interface.
APIs, for any network or code API released as v1.0.0 or later.
Observability data used in official dashboards, where the official set of dashboards are found in the alloy-mixin/ directory.

Exceptions

We strive to maintain backward compatibility, but there are situations that may arise that require a breaking change without a new major version, deviating from item 8 of the semver specification:

Security: A security issue may arise that requires breaking compatibility.
Legal requirements: If an exposed behavior violates a licensing or legal requirement, a breaking change may be required.
Specification errors: If a specification for a feature is found to be incomplete or inconsistent, fixing the specification may require a breaking change.
Bugs: If a bug is found that goes against the documented specification of that functionality, fixing the bug may require breaking compatibility for users who are relying on the incorrect behavior.
Upstream changes: Much of the functionality of Alloy is built on top of other software, such as OpenTelemetry Collector and Prometheus. If upstream software breaks compatibility, we may need to reflect this in Alloy.
Community components: Community components are components implemented and maintained by the community. They aren’t covered by the backward compatibility strategy.

We try, whenever possible, to resolve these issues without breaking compatibility.

Release cadence

Mon, 30 Mar 2026 16:59:33 +0000

Release cadence

A new minor release is planned every three weeks for Alloy. Patch releases are published every one to two weeks.

The release cadence is best-effort. If necessary, releases may be performed outside of this cadence, or a scheduled release date can be moved forwards or backwards.

Minor releases published on cadence include updating dependencies for upstream OpenTelemetry Collector code if new versions are available. Minor releases published outside of the release cadence may not include these dependency updates.

Patch and security releases may be created at any time.

Release information on Grafana Labs

Grafana Alloy backward compatibility

Grafana Alloy backward compatibility

Exceptions

Release cadence

Release cadence