--- title: "The OpenTelemetry Engine | Grafana Cloud documentation" description: "Learn how to run the OpenTelemetry Engine using the CLI, Helm chart, or service installation" --- # 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](/docs/grafana-cloud/send-data/alloy/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`. ### 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 and starts a Default Engine pipeline alongside the OTel Engine pipeline. The following example shows the configuration: 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: file: 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. - *``* : 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. 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`. ## 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 k8s liveliness 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. ## 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. **Fleet management**: [Grafana Fleet Management](/blog/opentelemetry-and-grafana-labs-whats-new-and-whats-next-in-2026/#fleet-management) doesn’t support the OTel Engine yet. You must define and manage the input configuration manually. ## Next steps - Refer to [OpenTelemetry in Alloy](/docs/grafana-cloud/send-data/alloy/introduction/otel_alloy) for information about the included components. - Refer to the [OTel CLI reference](/docs/grafana-cloud/send-data/alloy/reference/cli/otel) for more information about the OTel CLI.