--- title: "The OpenTelemetry Engine | Grafana Alloy documentation" description: "Learn how to run the OpenTelemetry Engine using the CLI, Helm chart, or service installation" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # The Alloy OpenTelemetry Engine You can run the OTel Engine using the CLI, Helm chart, or service installation. ## Prerequisites There are no additional prerequisites. The tools needed to run the OTel Engine are shipped within Alloy. Before you start, validate your OpenTelemetry YAML configuration with the `validate` command: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash alloy otel validate --config= ``` While this is an experimental feature, it isn’t hidden behind an `experimental` feature flag like regular components. This maintains compatibility with the OpenTelemetry Collector. ## Run with the CLI The OTel Engine is available under the Alloy `otel` command. The CLI is the easiest way to experiment locally or on a single host. Refer to the [OTel CLI](../../reference/cli/otel/) documentation for more information. The following example configuration file accepts telemetry over [OTLP](https://opentelemetry.io/docs/specs/otel/protocol/) and sends it to the configured backend: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml extensions: basicauth/my_auth: client_auth: username: password: receivers: otlp: protocols: grpc: {} http: {} processors: batch: timeout: 1s send_batch_size: 512 exporters: otlphttp/my_backend: endpoint: auth: authenticator: basicauth/my_auth service: extensions: [basicauth/my_auth] pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/my_backend] ``` Replace the following: - *``* : Your username. If you’re using Grafana Cloud, this is your Grafana Cloud instance ID. - *``* : Your password. If you’re using Grafana Cloud, this is your Grafana Cloud API token. - *``* : The URL to export data to. If you’re using Grafana Cloud, this is your Grafana Cloud OTLP endpoint URL. For more information about where to find these values for Grafana Cloud, refer to [Send data using OpenTelemetry Protocol](/docs/grafana-cloud/send-data/otlp/send-data-otlp/). To start the OTel Engine, run the following command: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell alloy otel --config= [ ...] ``` Alloy then accepts incoming OTLP data on `0.0.0.0:4317` for gRPC and `0.0.0.0:4318` for HTTP requests. Metrics are also available on the default collector port and endpoint at `0.0.0.0:8888/metrics`. Since the Default Engine isn’t running, the UI and metrics aren’t available at `0.0.0.0:12345/metrics`. ### 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`](../../reference/cli/otel-supervisor/) for setup instructions and required environment variables. ### Run the Alloy Engine extension You can also run the OTel Engine with the Default Engine. Modify your YAML configuration to include the `alloyengine` extension. This extension accepts a path to the Default Engine configuration or an inline Default Engine configuration. It starts a Default Engine pipeline alongside the OTel Engine pipeline. The following example uses `config.path` to load the Default Engine configuration from a file or directory: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml extensions: basicauth/my_auth: client_auth: username: password: alloyengine: config: path: flags: server.http.listen-addr: 0.0.0.0:12345 receivers: otlp: protocols: grpc: {} http: {} processors: batch: timeout: 1s send_batch_size: 512 exporters: otlphttp/my_backend: endpoint: auth: authenticator: basicauth/my_auth service: extensions: [basicauth/my_auth, alloyengine] pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/my_backend] ``` Replace the following: - *``* : The path to your Default Engine configuration file or directory. If you provide a directory, Alloy finds `*.alloy` files in it and loads them as a single configuration source. Refer to the [run command reference](../../reference/cli/run/) for more information. - *``* : Your username. If you’re using Grafana Cloud, this is your Grafana Cloud instance ID. - *``* : Your password. If you’re using Grafana Cloud, this is your Grafana Cloud API token. - *``* : The URL to export data to. If you’re using Grafana Cloud, this is your Grafana Cloud OTLP endpoint URL. To provide the Default Engine configuration inline, use `config.inline.content` instead of `config.path`: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml extensions: alloyengine: config: inline: content: | logging { level = "info" } ``` This example adds the `alloyengine` block in the extension declarations and enables the extension in the `service` block. You can then run Alloy with the exact same command as before: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell alloy otel --config= [ ...] ``` This command starts both the Default Engine and OTel Engine. The output of both engines is visible in the logs. You can access the Default Engine UI and metrics on port `12345`. > Warning > > Only one `alloyengine` extension can be active per process. ## Run with the OpenTelemetry Collector Helm chart Use the upstream [OpenTelemetry Collector Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-collector) to run the OTel Engine. This approach delivers an identical upstream collector experience. It also ensures you get improvements, bug fixes, and security updates as they’re released. The following example Helm `values.yaml` incorporates the same configuration seen above into a Kubernetes Deployment. > Note > > In this configuration, binding port `8888` to `0.0.0.0` makes the metrics endpoint listen on all interfaces inside the Pod. This lets other Pods in the cluster reach it without using `kubectl port-forward`. > > The configuration also sets the `command.name` key to `bin/otelcol`. This is the binary that runs the `alloy otel` sub-command. The Helm chart doesn’t expose custom commands, so this setting is necessary. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml image: repository: grafana/alloy tag: latest command: name: "bin/otelcol" mode: deployment ports: metrics: enabled: true alternateConfig: extensions: health_check: endpoint: 0.0.0.0:13133 # This is necessary for the Kubernetes liveness check basicauth/my_auth: client_auth: username: password: receivers: otlp: protocols: grpc: {} http: {} processors: batch: timeout: 1s send_batch_size: 512 exporters: otlphttp/my_backend: endpoint: 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: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/my_backend] ``` Replace the following: - *``* : Your username. If you’re using Grafana Cloud, this is your Grafana Cloud instance ID. - *``* : Your password. If you’re using Grafana Cloud, this is your Grafana Cloud API token. - *``* : The URL to export data to. If you’re using Grafana Cloud, this is your Grafana Cloud OTLP endpoint URL. The Helm chart ships with a default OpenTelemetry Collector configuration in the `config` field. The upstream Helm chart [documentation](https://opentelemetry.io/docs/platforms/kubernetes/helm/collector/#configuration) describes this field. If you want to completely override that default configuration, use the `alternateConfig` field. In the example above, the `alternateConfig` field ensures the configuration matches the other examples in this document and doesn’t inherit any of the chart’s defaults. Alternatively, you can omit both `config` and `alternateConfig` to use the default configuration as-is. You can also provide your own `config` block that merges with the chart’s default configuration. Refer to the [upstream documentation](https://opentelemetry.io/docs/platforms/kubernetes/helm/collector/) for more information about how to configure the helm chart to work for your use case. ## Run with service installation Service installation support for systemd, launchd, and similar systems isn’t included in the initial experimental release. Service installers work seamlessly with the OTel Engine as the feature matures. In the meantime, use the CLI or Helm options for testing. ## Custom builds with the OpenTelemetry Collector Builder (OCB) The OTel Engine is generated from a declarative [OpenTelemetry Collector Builder (OCB)](https://opentelemetry.io/docs/collector/custom-collector/) manifest. If you need additional components or want to remove bundled components, edit the manifest and build a customized Alloy binary. Grafana doesn’t offer commercial support for custom builds. 1. Clone the Alloy repository and change to the repository root. The following steps assume you run commands from this directory. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell git fetch --tags git checkout ``` Replace *``* with the [release tag](https://github.com/grafana/alloy/releases) you want. 2. Add or remove components by editing the OCB manifest in [`collector/builder-config.yaml`](https://github.com/grafana/alloy/blob/main/collector/builder-config.yaml). To **Remove** a component, delete its `- gomod: ...` line from the appropriate section. To **Add** a component, append a line that points at the module path and version you want. Follow the same `- gomod:` pattern as the other entries. 3. Build the full Alloy binary. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell make alloy ``` The binary in `build/` behaves like a standard `alloy` build. Use [`alloy otel`](../../reference/cli/otel/) to run collector YAML against your custom bundle. 4. Build the Alloy Docker image. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell make alloy-image =/ ``` Replace *``* with your image repository and image name. If you don’t set the image repository and image name, the build defaults to `grafana/alloy`. ## Considerations 1. **Storage configuration**: The Default Engine accepts the `--storage.path` flag to set a base directory for components to store data on disk. The OTel Engine uses the `filestorage` extension instead of a CLI flag. Refer to the [upstream documentation](https://opentelemetry.io/docs/collector/resiliency/#persistent-storage-write-ahead-log---wal) for more information. 2. **Server ports**: The Default Engine exposes its HTTP server on port `12345`. The OTel Engine exposes its HTTP server on port `8888`. The OTel Engine HTTP server doesn’t expose a UI, support bundles, or reload endpoint functionality like the Default Engine does. 3. **Inline configuration module path**: If `config.inline.module_path` isn’t defined, the `module_path` Alloy configuration keyword resolves to the process current working directory. ## Next steps - Refer to [OpenTelemetry in Alloy](../../introduction/otel_alloy/) to learn when to use each engine. - Refer to the [`otel` command reference](../../reference/cli/otel/) for the command options and included components.