Run the Alloy OpenTelemetry Engine with the CLI

The OTel Engine is available under the Alloy otel command. Use the CLI to experiment locally or to run the OTel Engine on a single host. Refer to the otel reference documentation for more information.

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 Alloy installed. Refer to Install Grafana Alloy for more information.

Run the OTel Engine

Create a configuration file named config.yaml. The following example accepts traces over OTLP and prints it to the console:

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Check the configuration:

alloy otel validate --config=config.yaml

Start the OTel Engine:
shell
```
alloy otel --config=config.yaml
```
To pass extra command-line flags, refer to the otel command reference.
Verify that the OTel Engine runs:
shell
```
curl http://localhost:8888/metrics
```

Alloy then accepts incoming OTLP traces on localhost:4317 for gRPC and localhost:4318 for HTTP requests. Metrics are also available on the default collector port and endpoint at localhost:8888/metrics.

The Default Engine isn’t running, so its UI at localhost:12345 and its metrics at localhost:12345/metrics aren’t available.

Send data to Grafana Cloud

The following example configuration accepts telemetry over OTLP and sends it to Grafana Cloud:

extensions:
  basicauth/my_auth:
    client_auth:
      username: "<USERNAME>"
      password: "<PASSWORD>"

receivers:
  otlp:
    protocols:
      grpc: {}
      http: {}

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

exporters:
  otlp_http/my_backend:
    endpoint: <URL>
    auth:
      authenticator: basicauth/my_auth

service:
  extensions: [basicauth/my_auth]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp_http/my_backend]

Replace the following:

<USERNAME>: Your Grafana Cloud instance ID.
<PASSWORD>: Your Grafana Cloud API token.
<URL>: Your Grafana Cloud OTLP endpoint URL.

For more information about where to find these values, refer to Send data using OpenTelemetry Protocol.

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 for setup instructions and required environment variables.