Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Grafana Alloybreadcrumb arrow Set upbreadcrumb arrow OpenTelemetry Enginebreadcrumb arrow Service installations
Grafana Cloud
Last reviewed: October 6, 2026

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:

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:

  1. Edit the environment file for the service:

    • Debian or Ubuntu: Edit /etc/default/alloy
    • RHEL/Fedora or SUSE/openSUSE: Edit /etc/sysconfig/alloy

  2. Set ALLOY_OTEL_MODE=1.

  3. 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.

  4. 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.

  5. Check the configuration, and replace <OTEL_CONFIG_FILE> with the path configured above:

    shell 
    alloy otel validate --config=<OTEL_CONFIG_FILE>

  6. Restart the service:

    shell 
    sudo systemctl restart alloy

  7. 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:

  1. Edit the file at $(brew --prefix)/etc/alloy/config.env.

  2. Set ALLOY_OTEL_MODE=1.

  3. 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.

  4. 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.

  5. Check the configuration:

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

  6. Restart the service:

    shell 
    brew services restart grafana/grafana/alloy

  7. 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:

  1. Open the Registry Editor and navigate to HKEY_LOCAL_MACHINE\SOFTWARE\GrafanaLabs\Alloy.

  2. Set the string value ALLOY_OTEL_MODE to 1.

  3. 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.

  4. 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.

  5. Check the configuration:

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

  6. Restart the Alloy service from the Windows Services manager.

  7. Verify that the OTel Engine runs:

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

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