Grafana Alloy Reference on Grafana Labs

The Grafana Alloy command-line interface

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

The Grafana Alloy command-line interface

The alloy binary exposes a command-line interface with subcommands to perform various operations.

The most common subcommand is run which accepts a configuration file and starts Alloy.

Available commands:

convert: Convert an Alloy configuration file.
fmt: Format an Alloy configuration file.
run: Start Alloy with the Default Engine, given an Alloy syntax configuration file.
otel: Start Alloy with the experimental OTel Engine, given an Open Telemetry Collector YAML configuration file.
tools: Read the WAL and provide statistical information.
completion: Generate shell completion for the alloy CLI.
help: Print help for supported commands.

Configuration blocks

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

Configuration blocks

Configuration blocks are optional top-level blocks that can be used to configure various parts of the Alloy process. Unlabeled configuration blocks can only be defined once.

Configuration blocks are not components, so they have no exports.

Components

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

Components

This section contains reference documentation for all recognized components. Refer to Choose a Grafana Alloy component for an overview of the components ecosystem.

Compatible components

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

Compatible components

This section provides an overview of some of the possible connections between compatible components in Alloy.

For each common data type, we provide a list of compatible components that can export or consume it.

Note
The type of export may not be the only requirement for chaining components together. The value of an attribute may matter as well as its type. Refer to each component’s documentation for more details on what values are acceptable.

For example:

A Prometheus component may always expect an "__address__" label inside a list of targets.

A string argument may only accept certain values like “traceID” or “spanID”.

Targets

Targets are a list(map(string)) - a list of maps with string values. They can contain different key-value pairs, and you can use them with a wide range of components. Some components require Targets to contain specific key-value pairs to work correctly. It’s recommended to always check component references for details when working with Targets.

Targets Exporters

The following components, grouped by namespace, export Targets.

Targets Consumers

The following components, grouped by namespace, consume Targets.

Prometheus `MetricsReceiver`

The Prometheus metrics are sent between components using MetricsReceivers. MetricsReceivers are capsules that are exported by components that can receive Prometheus metrics. Components that can consume Prometheus metrics can be passed the MetricsReceiver as an argument. Use the following components to build your Prometheus metrics pipeline:

Prometheus `MetricsReceiver` Exporters

The following components, grouped by namespace, export Prometheus MetricsReceiver.

Prometheus `MetricsReceiver` Consumers

The following components, grouped by namespace, consume Prometheus MetricsReceiver.

Loki `LogsReceiver`

LogsReceiver is a capsule that is exported by components that can receive Loki logs. Components that consume LogsReceiver as an argument typically send logs to it. Use the following components to build your Loki logs pipeline:

Loki `LogsReceiver` Exporters

The following components, grouped by namespace, export Loki LogsReceiver.

Loki `LogsReceiver` Consumers

The following components, grouped by namespace, consume Loki LogsReceiver.

OpenTelemetry `otelcol.Consumer`

The OpenTelemetry data is sent between components using otelcol.Consumers. otelcol.Consumers are capsules that are exported by components that can receive OpenTelemetry data. Components that can consume OpenTelemetry data can be passed the otelcol.Consumer as an argument. Some components that use otelcol.Consumer only support a subset of telemetry signals, for example, only traces. Refer to the component reference pages for more details on what is supported. Use the following components to build your OpenTelemetry pipeline:

OpenTelemetry `otelcol.Consumer` Exporters

The following components, grouped by namespace, export OpenTelemetry otelcol.Consumer.

OpenTelemetry `otelcol.Consumer` Consumers

The following components, grouped by namespace, consume OpenTelemetry otelcol.Consumer.

Pyroscope `ProfilesReceiver`

The Pyroscope profiles are sent between components using ProfilesReceivers. ProfilesReceivers are capsules that are exported by components that can receive Pyroscope profiles. Components that can consume Pyroscope profiles can be passed the ProfilesReceiver as an argument. Use the following components to build your Pyroscope profiles pipeline:

Pyroscope `ProfilesReceiver` Exporters

The following components, grouped by namespace, export Pyroscope ProfilesReceiver.

Pyroscope `ProfilesReceiver` Consumers

The following components, grouped by namespace, consume Pyroscope ProfilesReceiver.

Standard library

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

Standard library

The standard library is a list of functions you can use in expressions when assigning values to attributes.

All standard library functions are pure functions. The functions always return the same output if given the same input.

The Grafana Alloy HTTP endpoints

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

The Grafana Alloy HTTP endpoints

Grafana Alloy has several default HTTP endpoints that are available by default regardless of which components you have configured. You can use these HTTP endpoints to monitor, health check, and troubleshoot Alloy.

You can configure the HTTP server which exposes them with the http block and the --server. command line arguments. For example, if you set the --server.http.listen-addr command line argument to 127.0.0.1:12345, you can query the 127.0.0.1:12345/metrics endpoint to see the internal metrics of Alloy.

`/metrics`

The /metrics endpoint returns the internal metrics of Alloy in the Prometheus exposition format.

`/-/ready`

An Alloy instance is ready once it has loaded its initial configuration. If the instance is ready, the /-/ready endpoint returns HTTP 200 OK and the message Alloy is ready. Otherwise, if the instance isn’t ready, the /-/ready endpoint returns HTTP 503 Service Unavailable and the message Alloy is not ready.

`/-/healthy`

When all Alloy components are working correctly, all components are considered healthy. If all components are healthy, the /-/healthy endpoint returns HTTP 200 OK and the message All Alloy components are healthy.. Otherwise, if any of the components aren’t working correctly, the /-/healthy endpoint returns HTTP 500 Internal Server Error and an error message. You can also monitor component health through the Alloy UI.

curl localhost:12345/-/healthy
All Alloy components are healthy.

curl localhost:12345/-/healthy
unhealthy components: math.add

Note
The /-/healthy endpoint isn’t suitable for a Kubernetes liveness probe.

You don’t necessarily need to restart an Alloy instance that reports as unhealthy. For example, a component may be unhealthy due to an invalid configuration or an unavailable external resource. In this case, restarting Alloy would not fix the problem. A restart may make it worse, because it would stop the flow of telemetry in healthy pipelines.

`/-/reload`

The /-/reload endpoint reloads the Alloy configuration file. If the configuration file can’t be reloaded, the /-/reload endpoint returns HTTP 400 Bad Request and an error message.

curl localhost:12345/-/reload
config reloaded

curl localhost:12345/-/reload
error during the initial load: /Users/user1/Desktop/git.alloy:13:1: Failed to build component: loading custom component controller: custom component config not found in the registry, namespace: "math", componentName: "add"

`/-/support`

The /-/support endpoint returns a support bundle that contains information about your Alloy instance. You can use this information as a baseline when debugging an issue.

`/debug/pprof`

The /debug/pprof endpoint returns a pprof Go profile that you can use to visualize and analyze profiling data.

Release information

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

Release information

This section provides information about Alloy versioning policies and release schedules.

For product lifecycle information, refer to Grafana Cloud product lifecycle.

Grafana Alloy Reference on Grafana Labs

The Grafana Alloy command-line interface

The Grafana Alloy command-line interface

Configuration blocks

Configuration blocks

Components

Components

Compatible components

Compatible components

Targets

Targets Exporters

Targets Consumers

Prometheus MetricsReceiver

Prometheus MetricsReceiver Exporters

Prometheus MetricsReceiver Consumers

Loki LogsReceiver

Loki LogsReceiver Exporters

Loki LogsReceiver Consumers

OpenTelemetry otelcol.Consumer

OpenTelemetry otelcol.Consumer Exporters

OpenTelemetry otelcol.Consumer Consumers

Pyroscope ProfilesReceiver

Pyroscope ProfilesReceiver Exporters

Pyroscope ProfilesReceiver Consumers

Standard library

Standard library

The Grafana Alloy HTTP endpoints

The Grafana Alloy HTTP endpoints

/metrics

/-/ready

/-/healthy

/-/reload

/-/support

/debug/pprof

Release information

Release information

Prometheus `MetricsReceiver`

Prometheus `MetricsReceiver` Exporters

Prometheus `MetricsReceiver` Consumers

Loki `LogsReceiver`

Loki `LogsReceiver` Exporters

Loki `LogsReceiver` Consumers

OpenTelemetry `otelcol.Consumer`

OpenTelemetry `otelcol.Consumer` Exporters

OpenTelemetry `otelcol.Consumer` Consumers

Pyroscope `ProfilesReceiver`

Pyroscope `ProfilesReceiver` Exporters

Pyroscope `ProfilesReceiver` Consumers

`/metrics`

`/-/ready`

`/-/healthy`

`/-/reload`

`/-/support`

`/debug/pprof`