This is documentation for the next version of Grafana Alloy Documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Introductionbreadcrumb arrow OpenTelemetry in Alloy
Open source

OpenTelemetry in Alloy

Grafana Alloy combines the Prometheus-native, production-grade collection features of Alloy with the broad ecosystem and standards of OpenTelemetry. The Alloy OpenTelemetry Engine is an OpenTelemetry Collector distribution embedded within Alloy. It lets you run Alloy with the OpenTelemetry Collector while retaining access to all Alloy features and integrations.

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.

Terminology

Alloy supports two runtime engines and an extension:

  • Default Engine: The default Alloy runtime and configuration syntax. This remains the default, stable experience with backward compatibility guarantees for Alloy users.

  • OTel Engine: The standard OpenTelemetry Collector runtime embedded within Alloy. It uses upstream collector YAML configuration for pipelines and components.

  • Alloy Engine extension: An OpenTelemetry Collector extension that lets you run both the Default Engine and the OTel Engine at the same time.

Included components

The OTel Engine includes:

  • Standard components from the OpenTelemetry Collector Core repository
  • Selected components from the OpenTelemetry Collector Contrib repositories
  • The alloyengine extension

Alloy v1.17.0 bundles OpenTelemetry Collector components from version v0.153.0. You can find more information about the bundled version in both the OpenTelemetry Collector and OpenTelemetry Collector Contrib repositories.

The following sections list all included components:

To view the full list of components and their versions, refer to the OpenTelemetry Collector Builder manifest.

Custom builds with the OpenTelemetry Collector Builder (OCB)

The OTel Engine is generated from a declarative OpenTelemetry Collector Builder (OCB) 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

Clone the Git repository and change to the repository root. The following steps assume you run commands from this directory.

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 
git fetch --tags
git checkout <RELEASE_TAG>

Replace <RELEASE_TAG> with the release tag you want.

2. Start from the checked-in manifest

The source manifest is collector/builder-config.yaml in your checkout. You can:

  • Remove a component: delete its - gomod: ... line from the appropriate section.
  • 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 Alloy binary

Build the full Alloy binary:

shell 
make alloy

The binary in build/ behaves like a standard alloy build. Use alloy otel to run collector YAML against your custom bundle.

4. Build a Docker image

To create an image like the Grafana Alloy image:

shell 
make alloy-image <ALLOY_IMAGE>=<REGISTRY>/<IMAGE_NAME>

Replace <ALLOY_IMAGE> with your image repository and image name. If you don’t set the image repository and image name, the build defaults to grafana/alloy.

Next steps