Building a Secure OpenTelemetry Collector

By Martin Thwaites  |   Last modified on January 9, 2024

The OpenTelemetry Collector is a core part of telemetry pipelines, which makes it one of the parts of your infrastructure that must be as secure as possible. The general advice from the OpenTelemetry teams is to build a custom Collector executable instead of using the supplied ones when you’re using it in a production scenario. However, that isn’t an easy task, and that prompted me to build something.

In this post, we’ll go through how to build a custom Collector, including the new way I created using the standard OpenTelemetry Collector configuration.

If you just want to see the new stuff, take a look at the repository, or read the last section of this blog.

What does OpenTelemetry provide?

The OpenTelemetry team provides Docker images you can use:

  • OpenTelemetry core
    This is a limited image and includes components that are maintained by the core OpenTelemetry Collector team. The manifest includes all the components from the base OpenTelemetry Collector repo, but also includes some of the most commonly used components from the contrib repo like filter and attribute processors, and common exporters like Jaegar and Zipkin.
  • OpenTelemetry contrib
    This is the kitchen sink version. The manifest includes almost everything from the core and contrib repos, with some omissions where the components are in development.

Why aren’t these enough?

These images include too much of an attack surface. It’s as simple as that, in my eyes. Remember, code is a liability: aim for less, not more.

These images, even the core one, have more components than anyone requires. As an example, I’ve not yet come across a user (and I talk to a lot of you) that uses the OTLP, Zipkin, and Jaeger exporters in the same Collector. Including those would be a bad security practice as you’d include potential attack vectors that you don’t need.

For example, there was a long-standing vulnerability with the Jaeger receiver that couldn't be fixed until a Go upgrade was done. However, removing the Jaeger receiver wasn’t an option as it would break people’s environments expecting it. So, it had to be shipped.

You could use the argument that unless a component is in a pipeline it’s not executed, so it’s not a vulnerability. I’d love to see you convince security teams of that! Regardless, unless you do a code review and understand the vulnerability, you can’t definitively say that’s the case. And, that’s not something the OpenTelemetry Collector teams can do at scale.

What is the OpenTelemetry Collector builder?

The OpenTelemetry Collector team (specifically Juraci I believe) decided that creating OpenTelemetry Collector images should be easier, and people should be able choose their components. Therefore they created a tool that takes a manifest.yaml file that specifies the Go modules to include, and uses that to build a targeted distribution with a limited set of components.

A manifest looks like this:

  name: otelcol-custom
  description: OpenTelemetry Collector
  version: 0.91.0
  otelcol_version: 0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0
  - gomod: v0.91.0

This generates a very minimal Collector which, honestly, is what most people use. However, you can see that there is different syntax here for some of the modules. You need to know where they come from, you need to know the syntax, and there's also some inbuilt Go knowledge to know what gomod means.

The builder itself is solid, and I use it all the time to build custom images. However, I’ve been striving for a way to make it easier in pipelines and more accessible to people.

Building a custom Collector with a two stage build

One of the ways to make using the Collector builder easier is to use a two stage build and run everything inside the first container.

FROM golang:1.21 as build
RUN go install${OTEL_VERSION}
COPY . .
RUN CGO_ENABLED=0 builder --config=manifest.yaml --output-path=/app
COPY --from=build /app/otelcol-custom /
COPY config.yaml /
EXPOSE 4317/tcp 4318/tcp 13133/tcp
CMD ["/otelcol-custom", "--config=/config.yaml"]

With this, you still need to manually generate the manifest.yaml. However, you don’t need to install the builder or the Go SDK locally. This is really useful if you’re not interested in writing Go, or if you want to do things in a release pipeline. But we can do better!

Building a custom Collector with ocb-config-builder

I thought about how we could build the manifest file automatically, how we could remove the gomod problems and allow developers to pick the components they wanted instead of the Go modules.

I played with some custom yaml formats, but it all felt a little weird. Too many abstractions? Then, chatting with Tyler Helmuth about issues with the Collector builder, we had an epiphany… What if we just use the Collector config itself and map it?

This clicked with me. It’s DevEx 101 really: don’t leak your internal decisions to the user; speak their language and make it simple for them. Thus, the “OpenTelemetry Collector Builder Config Builder” was born! Yes, the name is bad. Naming is hard.

We still need to do a stage Docker build. However, we skipped the step of needing the manifest.yaml. Which also has the side benefit that now the Collector will never have unused components.

What does it look like?

FROM as build
COPY config.yaml /config/config.yaml
RUN /builder/ /config/config.yaml
COPY --from=build /app/otelcol-custom /
COPY config.yaml /
EXPOSE 4317/tcp 4318/tcp 13133/tcp
CMD ["/otelcol-custom", "--config=/config.yaml"]

Just make sure that your Collector config file is called config.yaml (or change it in the dockerfile). and you’ll have a tightly coupled Collector executable, in a secure container using the Chainguard base image to run it in production.


Having a custom OpenTelemetry Collector build doesn’t have to be complicated anymore. You don’t need to understand Go, or build config files. You can include this in your pipelines as a drop-in replacement for the collector-contrib image you’re likely using in production right now.

Hopefully this helps!

Happy collecting.


Related Posts


Data Sovereignty and OpenTelemetry

In today’s economic and regulatory environment, data sovereignty is increasingly top of mind for observability teams. The rules and regulations surrounding telemetry data can often...

OpenTelemetry   Instrumentation  

Avoid Stubbing Your Toe on Telemetry Changes

When you have questions about your software, telemetry data is there for you. Over time, you make friends with your data, learning what queries take...


Effective Trace Instrumentation with Semantic Conventions

There’s plenty of literature on the mechanics of instrumenting code with OpenTelemetry and delivering it to Honeycomb. However, I’ve not found many guides on the...