# Grafana Alloy: an OpenTelemetry Collector distribution with a config language

> Alloy is Grafana's OpenTelemetry Collector distribution, written in Go and licensed Apache-2.0. Its selling point is a programmable, expression-based pipeline language rather than a YAML pipeline tree, and it ships components for Prometheus, Loki, Pyroscope, Kubernetes and OTLP.

**grafana/alloy** — OpenTelemetry Collector distribution with programmable pipelines

- Repository: https://github.com/grafana/alloy
- Website: https://grafana.com/oss/alloy
- Stars: 3,566 · Forks: 720
- Language: Go
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/grafana-alloy

## The problem Alloy solves: one binary, four telemetry types, a real config language

Most collector deployments start as a YAML file and end as a directory of YAML files with anchors, environment substitution and copy-paste between receivers and exporters. Alloy's answer is a configuration language with expressions, so a pipeline is written as named components whose inputs and outputs are referenced by value. The README describes it as an "OpenTelemetry Collector distribution with built-in Prometheus pipelines and support for metrics, logs, traces, and profiles." That sentence is the scope: it is not a single-signal agent. The audience is platform and observability engineers who already run Grafana's stack or are moving onto OpenTelemetry and do not want to run separate agents for metrics, logs, traces and profiles. The README also states Alloy embraces Grafana's "big tent" philosophy and has components for OpenTelemetry Collector, Prometheus, Grafana Loki and Grafana Pyroscope, so the intended user is not necessarily a Grafana Cloud customer. Self-hosted Prometheus plus Loki is a supported shape.

## How an Alloy pipeline is wired: components, inputs and outputs

Alloy's unit of configuration is the component. Each component is declared with a block, given a label, configured with attributes, and connected to other components through an output block. The README example shows the pattern end to end: an OTLP receiver listens on gRPC, forwards metrics, logs and traces into a batch processor, which forwards all three into an OTLP exporter pointed at a remote endpoint.

```alloy
otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"
  }

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

The important detail is that the connection is expressed by referencing another component's input, not by naming an exporter in a string. That gives the config file a graph structure the tooling can read: the README lists a built-in UI for "visualizing and debugging pipelines," which only makes sense if the graph is known to the process. The same mechanism underlies modules, which the README describes as a way to share pipelines, and clustering, which it describes as automatic workload distribution across Alloy instances. Configuration can also be fetched from a server for centralized management, per the remotecfg reference. Those four features (graph-shaped config, modules, clustering, remote config) are the architectural bet: the config is data the program can reason about, not just text it parses once at startup.

## Installing Alloy and running a first OTLP pipeline

The README does not inline install commands. It points to the documentation for "Installation instructions for Alloy," then to a getting-started guide and the component reference, at grafana.com/docs/alloy/latest. Start there rather than guessing at package names. The repository does show how the binary is built from source: the Makefile documents an `alloy` target that compiles Alloy to $(ALLOY_BINARY), and the Dockerfile builds a container image from an Ubuntu Noble base, creating an `alloy` user with UID 473. If you build the image yourself, note the Dockerfile header states it requires BuildKit.

For a first real use, the smallest useful pipeline is the README's own example. Save it as a file, for instance `example-config.alloy` (that name exists at the top level of the repository), and start Alloy with that file as its config. The receiver listens on 127.0.0.1:4317 over gRPC, batches everything it receives, and exports to the OTLP endpoint you set in the exporter's client block. Replace `my-otlp-grpc-server:4317` with your own collector or backend address before running it.

```alloy
otelcol.exporter.otlp "default" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
  }
}
```

What you should see: an Alloy process with its built-in UI available for inspecting the pipeline, and traces, metrics and logs arriving at the downstream OTLP endpoint. If nothing arrives, the UI is the first place to look, since the README lists it under debugging utilities. The README does not document a rollback or dry-run flag, so treat config changes as live changes and keep the previous file.

## Where Alloy is the wrong tool

The clearest limitation is release churn. The README states a new minor release is planned every three weeks, with patch releases every one to two weeks, and adds that minor releases on cadence include updating dependencies for upstream OpenTelemetry Collector code. That is a fast-moving surface for a component that sits on the critical path of your telemetry. If your organisation upgrades infrastructure quarterly and treats config changes as change-controlled events, Alloy's cadence will fight your process. The README also frames the cadence as best-effort: releases may happen outside it, and scheduled dates can move. That is honest, but it means you cannot plan around a fixed calendar.

A second boundary is scope. Alloy is an OpenTelemetry Collector distribution, so it inherits that model: it is a pipeline, not a storage or query layer. If you want a single agent that also stores and queries, this is the wrong shape. Third, the programmable syntax is a real learning cost. Teams fluent in Collector YAML will not transfer that fluency for free; the README links a separate configuration-syntax concept page, which implies the language needs study. Finally, the README does not describe a stability guarantee for component interfaces, so anyone embedding Alloy components in their own Go program should read the changelog rather than assume the API holds.

## Alloy versus upstream OpenTelemetry Collector

The honest comparison is with the upstream OpenTelemetry Collector itself, which Alloy is a distribution of. The difference is in the configuration model and the bundled integrations, not in the wire protocol. Upstream Collector configurations are YAML: you declare receivers, processors and exporters in named lists, and connect them by listing exporter names inside a pipeline block. Alloy connects components by referencing another component's input in an output block, as the README example shows. Upstream gives you the canonical component set and the ecosystem's documentation; Alloy gives you that set plus its own components, a syntax with expressions, modules for sharing pipelines, clustering, and a UI that renders the graph. If your team already has a large YAML pipeline and no interest in a new language, staying upstream is defensible. If you want Prometheus scraping, Loki log shipping and OTLP in one process, Alloy's component list is the reason to switch. The README's "big tent" framing means you are not locked into Grafana backends, but the integrations that get first-class treatment are Grafana's.

## Maintenance, releases and licence

Alloy is not archived, and the last push to main was on 2026-09-23. Recent releases listed are v1.20.0-rc.0 on 2026-09-22, v1.19.2 on 2026-08-26 and v1.19.1 on 2026-08-26. The presence of a release candidate alongside a stable patch line tells you the project runs a pre-release channel; if you want stability, track the non-rc versions. The README's stated cadence (minor every three weeks, patch every one to two weeks) is the number to budget against, and the note that off-cadence minors may skip upstream Collector dependency updates means an off-cadence release is not automatically the better one.

The licence is Apache-2.0, per the repository's LICENSE file, and there is a separate LICENSING.md at the top level. That second file matters: a distribution that embeds components from many ecosystems often has per-component licence notes, and Apache-2.0 on the repository root does not by itself answer questions about every bundled dependency. Read LICENSING.md before shipping Alloy inside a product. This is not legal advice; it is a pointer to the file that carries the detail. The repository also ships a GOVERNANCE.md and a MAINTAINERS.md, which is useful if you need to know who decides what.

## Conclusion

Adopt Alloy if your telemetry already lands in Prometheus, Loki or Pyroscope and you want one binary whose pipeline you can read and edit as code, especially if you run Kubernetes and would rather configure it from inside the collector than from a separate operator. Do not adopt it if you need a stable config surface with no migration work: the README states a minor release is planned every three weeks, and the docs describe both a current syntax and a legacy one, so pin a version and read the changelog before upgrading. Before committing, verify the specific components you need exist in the reference component list, confirm the licence terms for the components you enable, and check that the release cadence matches your own maintenance window.

## FAQ

### How do I install Grafana Alloy?

The README points to the documentation for installation instructions rather than listing commands inline; the install guide lives at grafana.com/docs/alloy/latest/get-started/install/. You can also build the binary from source, where the Makefile documents an alloy target, or build the container image from the repository Dockerfile, which requires BuildKit.

### What is Grafana Alloy?

It is an open source OpenTelemetry Collector distribution with built-in Prometheus pipelines and support for metrics, logs, traces and profiles, written in Go and licensed Apache-2.0. It uses an expression-based configuration syntax in which components are connected through their inputs and outputs.

### What can I connect Grafana Alloy to?

The README lists components for OpenTelemetry Collector, Prometheus, Grafana Loki and Grafana Pyroscope, and describes the project as embracing Grafana's big tent philosophy so it can be used with other vendors or open source databases.

### How often does Grafana Alloy release new versions?

The README states a new minor release is planned every three weeks and patch releases every one to two weeks, with the cadence described as best-effort. Recent releases include v1.20.0-rc.0 on 2026-09-22 and v1.19.2 on 2026-08-26.

### Can Grafana Alloy share pipelines between instances?

Yes. The README lists modules as a way to share pipelines, clustering as a way to configure instances to form a cluster for automatic workload distribution, and remotecfg as support for retrieving configuration from a server.

## Sources

- [grafana/alloy on GitHub](https://github.com/grafana/alloy)
- [License: Apache-2.0](https://github.com/grafana/alloy/blob/main/LICENSE)
- [Project website](https://grafana.com/oss/alloy)
- [README](https://github.com/grafana/alloy/blob/main/README.md)
- [Releases](https://github.com/grafana/alloy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/grafana-alloy