Grafana Alloy 1.9: what changes in the telemetry collector

Grafana Alloy is an open source telemetry collector: one tool collects metrics, logs, traces and profiles, processes them and sends them to the backends you choose. Grafana Labs describes it as a distribution of the OpenTelemetry Collector with built-in Prometheus pipelines. In this article we explain what Alloy is for and how it replaces Grafana Agent, and then walk through version 1.9, based on the project’s official changelog. The release includes several breaking changes, so it is worth reading before you upgrade.

What Alloy is for

Alloy runs as an agent on a host, in a container or in a Kubernetes cluster. Its configuration is written in its own syntax as a set of components, each of which does one thing: it receives data, transforms it or sends it on. Components are wired into a pipeline that runs continuously. A single process can, for example:

• collect metrics from the host and from applications (built-in Prometheus exporters, including those for databases and Windows);
• receive OTLP data from applications instrumented with OpenTelemetry;
• read log files, containers and system journal entries and send them to Loki;
• send data to Grafana Cloud, your own Grafana stack or other backends that support OTLP and Prometheus.

This is useful if you want to stay with open standards. Alloy can be the collector in the architecture described in our article on OpenTelemetry alongside Elastic and Grafana, and its OTLP components let it send data to Elastic as well.

Alloy and Grafana Agent

Alloy is the successor to Grafana Agent. Grafana Labs is retiring the Agent and provides migration tooling: the alloy convert command turns an Agent configuration (static and Flow modes), as well as a Prometheus or OpenTelemetry Collector configuration, into an Alloy configuration. Before switching production, check the result of the conversion and run both collectors side by side on a single test host, because some Agent options have no direct equivalent. For larger environments it is worth splitting the migration into stages.

Version 1.9: breaking changes

Alloy ships new versions on a fixed schedule (roughly every six weeks), and 1.9 is the next release in that series. The most important changes, which may require fixes to your configuration:

• prometheus.exporter.oracledb now uses the official exporter maintained by Oracle instead of the earlier community one. As a result, three metrics are no longer enabled by default. If you have dashboards or alerts built on them, you need to enable them through a custom metrics file.
• prometheus.exporter.windows moved to a newer exporter version with a larger rework. The msmq and service collectors no longer support WMI where clauses, and several collectors were merged or removed.
• beyla.ebpf (an experimental component): the enable_context_propagation argument was replaced by context_propagation, which allows finer control over propagation.

The Oracle and Windows changes affect metrics, so after upgrading, compare the number of metric series and check that alerts still have data.

Version 1.9: new capabilities

According to the changelog, version 1.9 adds, among other things:

• the otelcol.storage.file component, an extension for persistent queues and state on disk, so that data is not lost on restart;
• the otelcol.receiver.splunkhec component, which receives data in Splunk HEC format (useful for a migration from Splunk);
• the community otelcol.exporter.googlecloud component;
• basic authentication for the Alloy HTTP server;
• a validate command that checks a configuration to a limited extent without starting Alloy;
• support for Cisco device modules in prometheus.exporter.snmp and for Mimir federated rule groups in mimir.rules.kubernetes;
• an update of the OpenTelemetry components from version 0.122.0 to 0.125.0.

After 1.9.0 the project publishes 1.9.x patch releases. When you upgrade, take the latest of them rather than the first.

Example OTLP pipeline in Alloy

The sketch below receives OTLP data, batches it and sends it to an OTLP backend. The address and token are examples.

otelcol.receiver.otlp "default" {
  grpc {}
  http {}

  output {
    metrics = [otelcol.processor.batch.default.input]
    logs    = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlp.backend.input]
    logs    = [otelcol.exporter.otlp.backend.input]
    traces  = [otelcol.exporter.otlp.backend.input]
  }
}

otelcol.auth.bearer "backend" {
  token = sys.env("OTLP_TOKEN")
}

otelcol.exporter.otlp "backend" {
  client {
    endpoint = "otlp.example.com:443"
    auth     = otelcol.auth.bearer.backend.handler
  }
}

How to upgrade safely

1. Read the breaking-changes section for every version you skip.
2. Back up your configuration and check it with the validate command and on a test host.
3. Upgrade one node first and watch Alloy’s own metrics and the continuity of data in dashboards for a day.
4. Only then upgrade the remaining agents. In large environments we do this in stages.

We handle the choice of collector, the deployment of Alloy and connecting it to Elastic or Grafana as part of infrastructure monitoring.