The Alloy OpenTelemetry Engine on Grafana Labs

Run the Alloy OpenTelemetry Engine with the CLI

Tue, 13 Oct 2026 15:26:25 +0000

Run the Alloy OpenTelemetry Engine with the CLI

The OTel Engine is available under the Alloy otel command. Use the CLI to experiment locally or to run the OTel Engine on a single host. Refer to the otel reference documentation for more information.

EXPERIMENTAL: OTel Engine is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.

To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability flag.

Make sure that you understand the risks involved before using an experimental feature in your production environments.

Before you begin

Make sure you have Alloy installed. Refer to Install Grafana Alloy for more information.

Run the OTel Engine

Create a configuration file named config.yaml. The following example accepts traces over OTLP and prints it to the console:

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Check the configuration:

alloy otel validate --config=config.yaml

Start the OTel Engine:
shell
```
alloy otel --config=config.yaml
```
To pass extra command-line flags, refer to the otel command reference.
Verify that the OTel Engine runs:
shell
```
curl http://localhost:8888/metrics
```

Alloy then accepts incoming OTLP traces on localhost:4317 for gRPC and localhost:4318 for HTTP requests. Metrics are also available on the default collector port and endpoint at localhost:8888/metrics.

The Default Engine isn’t running, so its UI at localhost:12345 and its metrics at localhost:12345/metrics aren’t available.

Send data to Grafana Cloud

The following example configuration accepts telemetry over OTLP and sends it to Grafana Cloud:

extensions:
  basicauth/my_auth:
    client_auth:
      username: "<USERNAME>"
      password: "<PASSWORD>"

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlp_http/my_backend:
    endpoint: <URL>
    auth:
      authenticator: basicauth/my_auth

service:
  extensions: [basicauth/my_auth]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/my_backend]

Replace the following:

<USERNAME>: Your Grafana Cloud instance ID.
<PASSWORD>: Your Grafana Cloud API token.
<URL>: Your Grafana Cloud OTLP endpoint URL.

For more information about where to find these values, refer to Send data using OpenTelemetry Protocol.

Manage with Grafana Fleet Management

Use the embedded otel-supervisor command to manage the OTel Engine through Grafana Fleet Management. The supervisor starts Alloy and receives OpenTelemetry Collector configuration from Grafana Fleet Management through OpAMP.

Refer to otel-supervisor for setup instructions and required environment variables.

Run the Grafana Alloy Engine extension

Tue, 13 Oct 2026 15:26:25 +0000

Run the Grafana Alloy Engine extension

You can run the OTel Engine and the Default Engine in the same process. Add the alloyengine extension to your OpenTelemetry Collector configuration to start a Default Engine pipeline alongside the OTel Engine pipeline. The two engines run in parallel and can’t exchange data with each other. If required, they can still communicate over the network via components like the OTLP exporter and receiver

Set exactly one of config.path or config.inline.content. The extension fails to start if you set both or neither.

EXPERIMENTAL: OTel Engine is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.

To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability flag.

Make sure that you understand the risks involved before using an experimental feature in your production environments.

Before you begin

Make sure you have the following:

An OpenTelemetry Collector configuration. To create one, refer to Run the OTel Engine with the CLI.
A Default Engine configuration file or directory.

Run both engines

Add the alloyengine extension to your Collector configuration, and enable it in the service block:
YAML
```
extensions:
  alloyengine:
    config:
      path: <ALLOY_CONFIG_PATH>
    flags:
      server.http.listen-addr: 0.0.0.0:12345

service:
  extensions: [alloyengine]
```
Replace <ALLOY_CONFIG_PATH> with the path to your Default Engine configuration file or directory. If you provide a directory, Alloy loads the *.alloy files in that directory as a single configuration source and ignores subdirectories.

The flags map passes command-line flags to the Default Engine. Refer to Pass flags to the Default Engine for details.

Keep your other extensions and service.extensions entries, and add alloyengine to them.
Start both engines:
shell
```
alloy otel --config=config.yaml
```
The output of both engines is visible in the logs.
Verify that the Default Engine runs by opening its UI at localhost:12345.

Pass flags to the Default Engine

Use the optional flags map to pass command-line flags to the Default Engine. Write each flag without the leading --. The example sets server.http.listen-addr to 0.0.0.0:12345 so the Default Engine UI accepts connections from other hosts. The default address, 127.0.0.1:12345, accepts connections only from the local host. Refer to the run command reference for the available flags.

Clustering is also supported this way, using the same cluster.* flags as the standalone Default Engine.

Provide the configuration inline

To provide the Default Engine configuration inline, use config.inline.content instead of config.path:

extensions:
  alloyengine:
    config:
      inline:
        content: |
          logging {
            level = "info"
          }

The module_path Alloy configuration keyword resolves to the value of config.inline.module_path. If you don’t set config.inline.module_path, module_path resolves to the current working directory of the Collector process.

Limitations

The Default Engine runs with some features disabled in extension mode. The remotecfg block isn’t supported, and configuration reload isn’t available. Use OpenTelemetry OpAMP for configuration management instead.

If the Default Engine configuration fails to load, the extension retries with exponential backoff, starting at 2 seconds and capping at 15 seconds. The Collector still reports the extension as ready, so a broken configuration doesn’t stop the OTel Engine. Check the /-/ready and /-/healthy endpoints of the Default Engine HTTP server for its actual state.

Warning
Only one alloyengine extension can be active per process. If you configure more than one, the first extension to start succeeds, the rest fail, and the Collector doesn’t start.

Embed the extension in another distribution

You can embed the alloyengine extension into any other OpenTelemetry Collector distribution with the OpenTelemetry Collector Builder (OCB). Refer to Include alloyengine extension in an OCB distribution for instructions.

Run the Alloy OpenTelemetry Engine with the OpenTelemetry Collector Helm chart

Tue, 13 Oct 2026 15:26:25 +0000

Run the Alloy OpenTelemetry Engine with the OpenTelemetry Collector Helm chart

Use the upstream OpenTelemetry Collector Helm chart to run the OTel Engine on Kubernetes. The chart deploys the Alloy image with the standard upstream chart values, so you configure it the same way you configure any OpenTelemetry Collector deployment.

EXPERIMENTAL: OTel Engine is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.

To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability flag.

Make sure that you understand the risks involved before using an experimental feature in your production environments.

Before you begin

Make sure you have the following:

Helm installed on your computer
A Kubernetes cluster that you can use for Alloy
A local Kubernetes context that points at the cluster

Run the OTel Engine

Add the OpenTelemetry Collector Helm chart repository:

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

Create a values.yaml file. The following example runs the configuration from Send data to Grafana Cloud in a Kubernetes Deployment:
YAML
```
image:
  repository: grafana/alloy
  tag: <ALLOY_VERSION>

command:
  name: "bin/otelcol"

mode: deployment

ports:
  metrics:
    enabled: true

config:
  extensions:
    basicauth/my_auth:
      client_auth:
        username: "<USERNAME>"
        password: "<PASSWORD>"

  receivers:
    otlp:
      protocols:
        grpc: {}
        http: {}
    jaeger: null
    zipkin: null
    prometheus: null

  processors:
    batch:
      timeout: 1s
      send_batch_size: 512

  exporters:
    debug: null
    otlp_http/my_backend:
      endpoint: <URL>
      auth:
        authenticator: basicauth/my_auth

  service:
    telemetry:
      metrics:
        readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888
    extensions: [basicauth/my_auth, health_check]
    pipelines:
      logs: null
      metrics: null
      traces:
        receivers: [otlp]
        processors: [batch]
        exporters: [otlp_http/my_backend]
```
Replace the following:
- <ALLOY_VERSION>: The Alloy release you want to run, for example v1.20.1.
- <USERNAME>: Your Grafana Cloud instance ID.
- <PASSWORD>: Your Grafana Cloud API token.
- <URL>: Your Grafana Cloud OTLP endpoint URL.
For more information about where to find the Grafana Cloud values, refer to Send data using OpenTelemetry Protocol.

The chart runs /<COMMAND_NAME> as the container command, so bin/otelcol resolves to /bin/otelcol. This path is a compatibility entrypoint in the Alloy image that runs alloy otel. Without this setting, the chart runs the image’s default entrypoint, which starts the Default Engine.

The example sets the chart defaults it doesn’t need to null and uses the chart’s own health_check extension without redefining it. Refer to the Helm chart documentation for how config combines with the chart’s defaults.

The example also sets the metrics endpoint host to 0.0.0.0 so it listens on all interfaces inside the Pod. The chart’s default binds the Pod IP, which other Pods in the cluster can already reach. Set 0.0.0.0 when you also want to reach the endpoint on 127.0.0.1 inside the Pod, for example from a sidecar container. Set ports.metrics.enabled to true to expose port 8888 on the Pod and the Service.

Install the chart:

helm install <RELEASE_NAME> open-telemetry/opentelemetry-collector --values values.yaml

Replace <RELEASE_NAME> with a name for your Helm release.

Verify that the Pod runs:
shell
```
kubectl get pods
```
The Pod reaches Running status once the OTel Engine starts.

Configuration options

Configure the OTel Engine through the chart’s config field, as the preceding example does. The Helm chart documentation describes this field and how your values combine with the chart’s defaults.

The chart also provides alternateConfig, which replaces the chart’s default configuration instead of combining with it. Upstream provides that field for use as a subchart and doesn’t recommend it when you install the chart directly.

Refer to the upstream documentation for more information about configuring the Helm chart for your use case.

Run the Alloy OpenTelemetry Engine with service installations

Tue, 13 Oct 2026 15:26:25 +0000

Run the Alloy OpenTelemetry Engine with service installations

The Alloy service installations for Linux, macOS, and Windows can run the OTel Engine instead of the Default Engine. Set ALLOY_OTEL_MODE to 1, true, yes, or on to run the OTel Engine. Matching is case-insensitive. If you don’t set ALLOY_OTEL_MODE, or you set it to any other value, Alloy runs the Default Engine.

No service installer exposes an install-time flag for this setting. Set it with the platform-specific mechanism below, then restart the service.

EXPERIMENTAL: OTel Engine is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.

To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability flag.

Make sure that you understand the risks involved before using an experimental feature in your production environments.

Before you begin

Make sure you have the following:

Alloy installed as a service. Refer to Install Grafana Alloy for more information.
An OpenTelemetry Collector configuration. To create one, refer to Run the OTel Engine with the CLI.

Linux

Alloy is installed as a systemd service on Linux. It reads ALLOY_OTEL_MODE from the systemd environment file.

To run the OTel Engine on Linux:

Edit the environment file for the service:
- Debian or Ubuntu: Edit /etc/default/alloy
- RHEL/Fedora or SUSE/openSUSE: Edit /etc/sysconfig/alloy
Set ALLOY_OTEL_MODE=1.
Edit the sample OpenTelemetry Collector configuration the package installs at /etc/alloy/config.yaml. The sample receives OTLP data and sends it to the debug exporter, which only writes to the console. Replace the debug exporter with a real backend. To use a different file, set OTEL_CONFIG_FILE to its path.
Optional: Set OTEL_CUSTOM_ARGS to pass additional command-line flags to the OTel Engine. This setting works the same way as CUSTOM_ARGS does for the Default Engine.
Check the configuration, and replace <OTEL_CONFIG_FILE> with the path configured above:
shell
```
alloy otel validate --config=<OTEL_CONFIG_FILE>
```
Restart the service:
shell
```
sudo systemctl restart alloy
```
Verify that the OTel Engine runs:
shell
```
curl http://localhost:8888/metrics
```

Refer to Pass additional command-line flags for more information about the environment file.

macOS

Alloy is installed as a launchd service on macOS. It reads ALLOY_OTEL_MODE from the Homebrew environment file.

To run the OTel Engine on macOS:

Edit the file at $(brew --prefix)/etc/alloy/config.env.
Set ALLOY_OTEL_MODE=1.
Create your OpenTelemetry Collector configuration at $(brew --prefix)/etc/alloy/config.yaml. The Homebrew formula doesn’t create this file, and the service always loads it.

To load an additional file, add --config=<PATH> to $(brew --prefix)/etc/alloy/otel-extra-args.txt. Alloy applies this flag after the default, so its values override the installer’s default where they overlap. Create config.yaml even when you use this option.
Optional: Add command-line flags for the OTel Engine to $(brew --prefix)/etc/alloy/otel-extra-args.txt. This file works the same way as extra-args.txt does for the Default Engine.

Check the configuration:

alloy otel validate --config=$(brew --prefix)/etc/alloy/config.yaml

Restart the service:

brew services restart grafana/grafana/alloy

Verify that the OTel Engine runs:
shell
```
curl http://localhost:8888/metrics
```

Refer to Configure environment variables for more information about the environment file.

Windows

Alloy is installed as a Windows Service. It reads ALLOY_OTEL_MODE from the Windows registry at HKLM\Software\GrafanaLabs\Alloy.

To run the OTel Engine on Windows:

Open the Registry Editor and navigate to HKEY_LOCAL_MACHINE\SOFTWARE\GrafanaLabs\Alloy.
Set the string value ALLOY_OTEL_MODE to 1.
Edit the sample OpenTelemetry Collector configuration the installer creates at %PROGRAMFILES%\GrafanaLabs\Alloy\config.yaml. The sample receives OTLP data and sends it to the debug exporter, which only writes to the log. Replace the debug exporter with a real backend. To use a different file, add --config=<PATH> to the multi-string value OTelArguments. Alloy applies this flag after the default, so its values override the installer’s default where they overlap.
Optional: Add command-line flags for the OTel Engine to the multi-string value OTelArguments. This value works the same way as Arguments does for the Default Engine.

Check the configuration:

& "$env:PROGRAMFILES\GrafanaLabs\Alloy\alloy-windows-amd64.exe" otel validate --config="$env:PROGRAMFILES\GrafanaLabs\Alloy\config.yaml"

Restart the Alloy service from the Windows Services manager.

Verify that the OTel Engine runs:

Invoke-WebRequest http://localhost:8888/metrics -UseBasicParsing

Refer to Service configuration for more information about the registry values Alloy uses.

Build a custom Grafana Alloy binary with the OpenTelemetry Collector Builder (OCB)

Tue, 13 Oct 2026 15:26:25 +0000

Build a custom Grafana Alloy binary with the OpenTelemetry Collector Builder (OCB)

Grafana builds the OTel Engine from a declarative OpenTelemetry Collector Builder (OCB) manifest. If you need additional components or want to remove bundled components, edit the manifest and build a customized Alloy binary.

Caution
Grafana doesn’t offer commercial support for custom builds.

EXPERIMENTAL: OTel Engine is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement.

To maintain full compatibility of the OTel Engine with the upstream OpenTelemetry Collector and expose a compatible command line interface, the OTel Engine isn’t hidden behind a stability flag.

Make sure that you understand the risks involved before using an experimental feature in your production environments.

Before you begin

Make sure you have the following tools:

Git
Go 1.26.7 or later
Node.js
Docker, if you want to build the container image

The build compiles C dependencies, so you also need the following for your platform:

On Linux, the systemd headers. On Debian-based distributions, run sudo apt-get install libsystemd-dev.
On Windows, a 64-bit mingw-w64 gcc toolchain. Grafana recommends the WinLibs build.

Build a custom binary

Clone the Alloy repository and change to the repository root. The following steps assume you run commands from this directory.
shell
```
git clone https://github.com/grafana/alloy.git
cd alloy
```
To build from a specific release, fetch tags and check out the tag after you clone:
shell
```
git fetch --tags
git checkout <RELEASE_TAG>
```
Replace <RELEASE_TAG> with the release tag you want.
Add or remove components by editing the OCB manifest in collector/builder-config.yaml.

To remove a component, delete its entire entry from the appropriate section. To add a component, append an entry that points at the module path and version you want. Follow the same - gomod: pattern as the other entries.
Build the full Alloy binary.
shell
```
make alloy
```
This command regenerates the collector distribution from the manifest before it builds, so your manifest edits take effect. The binary in build/ behaves like a standard alloy build. To skip the UI build when the UI assets already exist, run SKIP_UI_BUILD=1 make alloy. Use alloy otel to run collector YAML against your custom bundle.
Confirm that your components are in the build.
shell
```
./build/alloy otel components
```
The command lists each bundled component with its module path, version, and stability level.
Optional: Build the Alloy Docker image.
shell
```
make alloy-image ALLOY_IMAGE=<REGISTRY>/<IMAGE_NAME>:<TAG>
```
Set ALLOY_IMAGE to your own registry and image name.

Replace the following:
- <REGISTRY>: Your container registry.
- <IMAGE_NAME>: Your image name.
- <TAG>: Your image tag.