Documentation Grafana Alloy Set up OpenTelemetry Engine Service installations

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.

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:

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 Copy

   alloy otel validate --config=<OTEL_CONFIG_FILE>

6. Restart the service:

   shell Copy

   sudo systemctl restart alloy

7. Verify that the OTel Engine runs:

   shell Copy

   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 Copy

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

6. Restart the service:

   shell Copy

   brew services restart grafana/grafana/alloy

7. Verify that the OTel Engine runs:

   shell Copy

   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 Copy

   & "$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 Copy

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

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