Customizing an OpenTelemetry Collector Container Image

Addo Zhang
3 min readMar 5, 2024

OpenTelemetry Collector offers two official distributions: Core and Contrib.

  • The Core distribution serves as the base version of the Collector for OTel developers to develop and test. It includes a basic set of extensions, connectors, receivers, processors, and exporters.
  • The Contrib distribution is intended for non-OTel developers for experimentation and learning. It extends the Core distribution and includes components created by third parties (including vendors and individual community members) that are very useful for the entire OpenTelemetry community. In a previous article, “Efficient Application Log Collection and Analysis with OpenTelemetry and Loki,” I used this distribution.

Neither Core nor Contrib should be part of your production workload. Using only Core is overly simplistic and unlikely to meet organizational needs (even though its components are essential); while Contrib provides a comprehensive set of components, not every component may be necessary, leading to bloat and an increased attack surface.

So, how do you choose the right distribution for your needs? The answer is to build your own. You can use an official tool called the OpenTelemetry Collector Builder (OCB) to customize your build.

Installing OCB

OCB is a simple CLI tool that supports Windows, Linux, macOS, and both x86 and arm64 platforms. You can download the OCB binary from the release page.

curl -o ocb -sL
chmod +x ocb

You can check the usage with ./ocb help.

It can also be installed via go install.

go install

To build your own distribution, use the command below with --config to specify the configuration file, which is the build manifest discussed next.

./ocb --config=builder-config.yaml

If not provided, it uses the default manifest file. Since we’re building our own distribution, let’s see how to configure the build manifest.

Build Manifest

The build manifest describes the OpenTelemetry Collector and typically includes the following sections:

  • dist: Basic information about the distribution
  • receivers: List of integrated receivers
  • exporters: List of integrated exporters
  • extensions: List of integrated extensions
  • processors: List of integrated processors
  • connectors: List of integrated connectors

You can find the build manifest for the core distribution in the GitHub repository, which can be trimmed (remove the replace parts) to suit your needs.

name: otelcorecol
description: Local OpenTelemetry Collector binary, testing only.
version: 0.95.0-dev
otelcol_version: 0.95.0
output_path: /tmp/dist

Now, to build an OpenTelemetry Collector distribution for the article mentioned at the beginning, add lokiexporter to the exporters. More components can be found in the contrib repository.

This prepares the build manifest. Execute the command below, and you’ll find the built binary in the directory specified by dist.output_path.

./ocb --config=builder-config.yaml

Building the Image

Use the method above to build the collector’s binary file, and then further build a container image.

FROM golang:1.21 as build
COPY . .
RUN go install${OTEL_VERSION}
RUN CGO_ENABLED=0 builder --config=builder-config.yaml
COPY --from=build /tmp/dist/otelcorecol /
# 4317 - default OTLP receiver
# 55678 - op
encensus (tracing) receiver
# 55679 - zpages
EXPOSE 4317/tcp 55678/tcp 55679/tcp
CMD ["--config", "/etc/otelcol-contrib/config.yaml"]
ENTRYPOINT ["/otelcorecol"]

I’ve already built the image addozhang/opentelemetry-collector:0.95.0. When creating the CR OpenTelemetryCollector, you can change the image to our custom-built image.



Addo Zhang

CNCF Ambassador | LF APAC OpenSource Evangelist | Microsoft MVP | SA and Evangelist at | Programmer | Blogger | Mazda Lover | Ex-BBer