Build a custom Collector with OpenTelemetry Collector Builder

The OpenTelemetry Collector has five official distributions that come pre-configured with certain components. If you require more flexibility, you can use the OpenTelemetry Collector Builder (or ocb) to generate a custom binary of your own distribution that includes custom components, upstream components, and other publicly available components.

The following guide shows you how to get started with ocb to build your own Collector. In this example, you create a Collector distribution to support the development and testing of custom components. You can launch and debug your Collector components directly in your preferred Golang integrated development environment (IDE). Use all the debugging features of your IDE (stack traces are great teachers!) to understand how the Collector interacts with your component code.

Prerequisites

The ocb tool requires Go to build the Collector distribution. Make sure to install a compatible version of Go on your machine before you begin.

Install the OpenTelemetry Collector Builder

The ocb binary is available as a downloadable asset from OpenTelemetry Collector releases with cmd/builder tags. Find and download the asset that fits your operating system and chipset:

• Linux (AMD 64)
• Linux (ARM 64)
• Linux (ppc64le)
• macOS (AMD 64)
• macOS (ARM 64)
• Windows (AMD 64)

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.143.0/ocb_0.143.0_linux_amd64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.143.0/ocb_0.143.0_linux_arm64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.143.0/ocb_0.143.0_linux_ppc64le
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.143.0/ocb_0.143.0_darwin_amd64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.143.0/ocb_0.143.0_darwin_arm64
chmod +x ocb

Invoke-WebRequest -Uri "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.143.0/ocb_0.143.0_windows_amd64.exe" -OutFile "ocb.exe"
Unblock-File -Path "ocb.exe"

To make sure ocb is installed correctly, enter ./ocb help in your terminal. You should see the output of the help command in your console.

Configure the OpenTelemetry Collector Builder

Configure ocb with a YAML manifest file. The manifest has two main sections. The first section, dist, contains options for configuring code generation and the compile process. The second section contains top-level module types, such as extensions, exporters, receivers or processors. Each module type accepts a list of components.

The dist section of the manifest contains tags that are equivalent to ocb command line flags. The following table lists the options for configuring the dist section.

All dist tags are optional. You can add custom values for them depending on whether you intend to make your custom Collector distribution available to other users or you are using ocb to bootstrap your component development and testing environment.

To configure ocb, follow these steps:

1. Create a manifest file named builder-config.yaml with the following content:

   dist:
     name: otelcol-dev
     description: Basic OTel Collector distribution for Developers
     output_path: ./otelcol-dev
   

2. Add modules for the components you want to include in this custom Collector distribution. See the ocb configuration documentation to understand the different modules and how to add components.

   For this example distribution, add the following components:

   • Exporters: OTLP and Debug
   • Receivers: OTLP
   • Processors: Batch

   The builder-config.yaml manifest file should look like this:

   dist:
     name: otelcol-dev
     description: Basic OTel Collector distribution for Developers
     output_path: ./otelcol-dev
   
   exporters:
     - gomod:
         go.opentelemetry.io/collector/exporter/debugexporter v0.143.0
     - gomod:
         go.opentelemetry.io/collector/exporter/otlpexporter v0.143.0
   
   processors:
     - gomod:
         go.opentelemetry.io/collector/processor/batchprocessor v0.143.0
   
   receivers:
     - gomod:
         go.opentelemetry.io/collector/receiver/otlpreceiver v0.143.0
   
   providers:
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/envprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/fileprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/httpprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.48.0
   

Generate the code and build your Collector distribution

With ocb installed and configured, you are ready to build your distribution.

In your terminal, type the following command to start ocb:

./ocb --config builder-config.yaml

The output of the command looks like this:

2025-06-13T14:25:03.037-0500	INFO	internal/command.go:85	OpenTelemetry Collector distribution builder	{"version": "0.143.0", "date": "2025-06-03T15:05:37Z"}
2025-06-13T14:25:03.039-0500	INFO	internal/command.go:108	Using config file	{"path": "builder-config.yaml"}
2025-06-13T14:25:03.040-0500	INFO	builder/config.go:99	Using go	{"go-executable": "/usr/local/go/bin/go"}
2025-06-13T14:25:03.041-0500	INFO	builder/main.go:76	Sources created	{"path": "./otelcol-dev"}
2025-06-13T14:25:03.445-0500	INFO	builder/main.go:108	Getting go modules
2025-06-13T14:25:04.675-0500	INFO	builder/main.go:87	Compiling
2025-06-13T14:25:17.259-0500	INFO	builder/main.go:94	Compiled	{"binary": "./otelcol-dev/otelcol-dev"}

As defined in the dist section of your manifest, you now have a folder named otelcol-dev containing all the source code and the binary for your Collector distribution.

The folder structure looks like this:

.
├── builder-config.yaml
├── ocb
└── otelcol-dev
    ├── components.go
    ├── components_test.go
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── main_others.go
    ├── main_windows.go
    └── otelcol-dev

You can use the generated code to bootstrap your component development projects and then build and distribute your own Collector distribution with those components.

Containerize your Collector distribution

Follow these steps to containerize your custom Collector.

1. Add two new files to your project:

   • Dockerfile - Container image definition of your Collector distribution
   • collector-config.yaml - Minimal Collector configuration YAML for testing your distribution

   After adding these files, your file structure looks like this:

   .
   ├── builder-config.yaml
   ├── collector-config.yaml
   └── Dockerfile
   

2. Add the following content to the Dockerfile. This definition builds your Collector distribution in-place and ensures the resulting Collector distribution binary matches the target container architecture (for example, linux/arm64, linux/amd64):

   FROM alpine:3.19 AS certs
   RUN apk --update add ca-certificates
   
   FROM golang:1.25.0 AS build-stage
   WORKDIR /build
   
   COPY ./builder-config.yaml builder-config.yaml
   
   RUN --mount=type=cache,target=/root/.cache/go-build GO111MODULE=on go install go.opentelemetry.io/collector/cmd/builder@v0.143.0
   RUN --mount=type=cache,target=/root/.cache/go-build builder --config builder-config.yaml
   
   FROM gcr.io/distroless/base:latest
   
   ARG USER_UID=10001
   USER ${USER_UID}
   
   COPY ./collector-config.yaml /otelcol/collector-config.yaml
   COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
   COPY --chmod=755 --from=build-stage /build/otelcol-dev /otelcol
   
   ENTRYPOINT ["/otelcol/otelcol-dev"]
   CMD ["--config", "/otelcol/collector-config.yaml"]
   
   EXPOSE 4317 4318 12001
   

3. Add the following definition to your collector-config.yaml file:

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   
   exporters:
     debug:
       verbosity: detailed
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         exporters: [debug]
       metrics:
         receivers: [otlp]
         exporters: [debug]
       logs:
         receivers: [otlp]
         exporters: [debug]
   

4. Use the following commands to build a multi-architecture Docker image of ocb using linux/amd64 and linux/arm64 as the target build architectures. To learn more, see this blog post about multi-architecture builds.

   # Enable Docker multi-arch builds
   docker run --rm --privileged tonistiigi/binfmt --install all
   docker buildx create --name mybuilder --use
   
   # Build the Docker image as Linux AMD and ARM
   # and load the result to "docker images"
   docker buildx build --load \
     -t <collector_distribution_image_name>:<version> \
     --platform=linux/amd64,linux/arm64 .
   
   # Test the newly built image
   docker run -it --rm -p 4317:4317 -p 4318:4318 \
       --name otelcol <collector_distribution_image_name>:<version>
   

Further reading

• Build a receiver
• Build a connector