Release information on Grafana Labs

Grafana Alloy backward compatibility

Wed, 17 Jun 2026 08:38:37 +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

Wed, 17 Jun 2026 08:38:37 +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.

Grafana Alloy maintenance scope

Wed, 17 Jun 2026 08:38:37 +0000

Grafana Alloy maintenance scope

This page defines maintenance scope for Alloy, including both the Default Engine and the OTel Engine. Alloy includes code maintained by the Alloy maintainers and upstream dependencies maintained by open source communities.

For full context, read this page together with Alloy backward compatibility and the Grafana release life cycle.

Maintenance levels

Maintained: The feature is maintained by Alloy maintainers or within Grafana open-source projects integrated with Alloy.
Maintained with upstream dependency: The feature depends on upstream projects outside the Grafana open source ecosystem. Final resolution may depend on the upstream community’s review and release processes.
Not maintained by Alloy maintainers: The feature is outside the standard maintenance scope of Alloy maintainers.

Maintained

Example features include:

Core Default Engine runtime and operational experience, including installation, running, and configuration flow. For engine terminology and differences, refer to OpenTelemetry in Alloy.
Alloy platform capabilities such as Alloy configuration syntax, clustering, Fleet Management, and the built-in debugging UI.
Alloy installation scripts, Helm chart deployment, and bundled Grafana dashboards.
Alloy-owned integration points around the OTel Engine, such as the alloyengine extension.
Features based on Grafana open source projects integrated with Alloy, such as Mimir, Loki, Beyla, Tempo, Faro, Pyroscope, and Database Observability.

For maintained features, the Alloy maintainers can implement fixes and new features as needed with minimal friction and coordination overhead.

Maintained with upstream dependency

Example features include:

Features built on bundled upstream OpenTelemetry Collector components or Prometheus-related projects.
Compatibility behavior tied to upstream protocols, formats, and ecosystem standards (for example OTLP and Prometheus Remote Write protocols).
OTel Engine configuration and features that depend on the upstream OpenTelemetry Collector core engine.

The Alloy maintainers can investigate and collaborate upstream, but resolution timing may depend on upstream acceptance and release timing. In some cases, maintainers may carry a temporary patch or fork, but this is case-by-case and not guaranteed.

Not maintained by Alloy maintainers

Example features include:

Community components.
Custom or non-standard components added to custom Alloy builds via OCB or otherwise.

The Alloy maintainers may still contribute to fixing issues or implementing new features, but this isn’t guaranteed and is done on a best-effort basis.

Extending Alloy with OCB and custom builds

With OTel Engine, you can use the OpenTelemetry Collector Builder (OCB) to build a customized Alloy binary, including adding components or removing components from the standard release. The Alloy OCB manifest is the starting point for custom builds.

Response to issues usually follows the standard scope when the issue is unrelated to customizations or reproducible with the standard, maintained Alloy release. Response to issues may be limited when behavior can’t be isolated from customizations and can’t be reproduced with the standard, maintained Alloy release.

Release information on Grafana Labs

Grafana Alloy backward compatibility

Grafana Alloy backward compatibility

Exceptions

Release cadence

Release cadence

Grafana Alloy maintenance scope

Grafana Alloy maintenance scope

Maintenance levels

Maintained

Maintained with upstream dependency

Not maintained by Alloy maintainers

Extending Alloy with OCB and custom builds

Further reading