Documentation Grafana Alloy Set up OpenTelemetry Engine Alloy Engine extension

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.

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

1. Add the alloyengine extension to your Collector configuration, and enable it in the service block:

   YAML Copy

   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.

2. Start both engines:

   shell Copy

   alloy otel --config=config.yaml

   The output of both engines is visible in the logs.

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

YAML Copy

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.

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.