Documentationbreadcrumb arrow breadcrumb arrow Grafana Alloybreadcrumb arrow OpenTelemetry Enginebreadcrumb arrow Get Started

Get Started with 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 
./build/alloy otel validate --config=<CONFIG_FILE>

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 documentation for more information.

The following example configuration file accepts telemetry over OTLP and sends it to the configured backend:

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

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

processors:
  batch:
    timeout: 1s
    send_batch_size: 512

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

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

Replace the following:

  • <USERNAME>: Your username, if you are using Grafana Cloud this will be your Grafana Cloud instance ID.
  • <PASSWORD>: Your password, if you are using Grafana Cloud this will be your Grafana Cloud API token.
  • <URL>: The URL to export data to, if you are using Grafana Cloud this will be 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.

To start the OTel Engine, run the following command:

shell 
alloy otel --config=<CONFIG_FILE> [<FLAGS> ...]

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, which 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 
extensions:
  basicauth/my_auth:
    client_auth:
      username: <USERNAME>
      password: <PASSWORD>
  alloyengine:
    config:
      file: <ALLOY_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: <URL>
    auth:
      authenticator: basicauth/my_auth

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

Replace the following:

  • <ALLOY_CONFIG_PATH>: The path to your Default Engine configuration file.
  • <USERNAME>: Your username, if you are using Grafana Cloud this will be your Grafana Cloud instance ID.
  • <PASSWORD>: Your password, if you are using Grafana Cloud this will be your Grafana Cloud API token.
  • <URL>: The URL to export data to, if you are using Grafana Cloud this will be 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 
alloy otel --config=<CONFIG_FILE> [<FLAGS> ...]

This 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 Alloy Helm chart

TODO

Run with service installation

Service installation support for systemd, launchd, and similar systems isn’t included in the initial experimental release. Service installers will 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 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.
  3. Fleet management: Grafana Fleet Management isn’t supported yet for the OTel Engine. You must define and manage the input configuration manually.