Build a custom Grafana Alloy binary with the OpenTelemetry Collector Builder (OCB)

Grafana builds the OTel Engine 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.

Caution
Grafana doesn’t offer commercial support for custom builds.

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 the following tools:

Git
Go 1.26.7 or later
Node.js
Docker, if you want to build the container image

The build compiles C dependencies, so you also need the following for your platform:

On Linux, the systemd headers. On Debian-based distributions, run sudo apt-get install libsystemd-dev.
On Windows, a 64-bit mingw-w64 gcc toolchain. Grafana recommends the WinLibs build.

Build a custom binary

Clone the Alloy 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.
Add or remove components by editing the OCB manifest in collector/builder-config.yaml.
To remove a component, delete its entire entry from the appropriate section. To add a component, append an entry that points at the module path and version you want. Follow the same - gomod: pattern as the other entries.
Build the full Alloy binary.
shell
```
make alloy
```
This command regenerates the collector distribution from the manifest before it builds, so your manifest edits take effect. The binary in build/ behaves like a standard alloy build. To skip the UI build when the UI assets already exist, run SKIP_UI_BUILD=1 make alloy. Use alloy otel to run collector YAML against your custom bundle.
Confirm that your components are in the build.
shell
```
./build/alloy otel components
```
The command lists each bundled component with its module path, version, and stability level.
Optional: Build the Alloy Docker image.
shell
```
make alloy-image ALLOY_IMAGE=<REGISTRY>/<IMAGE_NAME>:<TAG>
```
Set ALLOY_IMAGE to your own registry and image name.
Replace the following:
- <REGISTRY>: Your container registry.
- <IMAGE_NAME>: Your image name.
- <TAG>: Your image tag.