Before learning the tool, it helps to understand the problem it solves.

The OpenTelemetry Collector is a program that receives telemetry such as traces, metrics and logs, optionally changes it, and sends it onward to storage and analysis systems. It does this through small building blocks called components. A receiver accepts data, a processor transforms it, and an exporter sends it away. The project offers hundreds of such components, covering an enormous range of technologies, from popular databases and cloud services to message systems and monitoring formats.

No single organisation uses all of them. A typical company needs perhaps a handful of receivers, a few processors and one or two exporters. If every Collector in the company carries hundreds of unused components, several things happen quietly. The program file is larger than it needs to be, which slows downloads and container startups. More code means more places where a security flaw can hide. More dependencies mean more updates to track. And when something goes wrong, there is more to search through.

Each term below comes with what it is, why it exists, and a picture to hold in your head.

OCB is one of several ways to get a Collector, so let us see where it sits among the options.

The OpenTelemetry project publishes several official distributions. The core distribution contains the essential components and is deliberately small. The contrib distribution adds a very large set of extra receivers, processors, exporters and extensions, contributed by the wider community. There is also a variant tuned for Kubernetes environments, one focused on the OpenTelemetry protocol, and a specialised variant for profiling with eBPF technology. Each distribution lists its components in a manifest file in the project’s repositories.

Beyond the official ones, many vendors publish their own distributions. Cloud providers and observability companies package the Collector with the components that work best with their platforms. The OpenTelemetry project lists these as community resources but does not validate or endorse them, so teams choosing a vendor distribution should read the vendor’s own support and security statements.

The whole workflow is a short chain with five links.

Notice how little you must write. You do not write Go code for the standard case. You write a list, and OCB turns the list into a working program. That is the whole promise of the tool: turn a short, readable description into a repeatable build.

Understanding the machinery removes the mystery and helps when something goes wrong.

OCB is a command-line program. When you run it with your manifest, it performs two broad jobs. First it generates source code: a small Go project containing a main program, a file that registers each component you listed, and the module files that record which versions of everything are needed. Second it compiles that project by calling the Go toolchain, which downloads the listed components from their module addresses and links everything into a single executable.

Because the output includes both the generated source and the finished binary, you can inspect exactly what was assembled. This is useful for debugging, for security reviews, and for developers who want to build their own components and test them inside a real Collector.

flowchart LR
    M["Manifest file: your component list"] --> O["OCB reads and validates it"]
    O --> G["Generate Go project: main, components, module files"]
    G --> D["Go toolchain downloads component modules"]
    D --> C["Compile and link"]
    C --> B["Single custom Collector binary"]
        

Installation is simple, but there is one prerequisite that surprises beginners.

OCB is distributed as a ready-to-run executable for the common platforms: Linux on both Intel-style and ARM processors, macOS, and Windows. On macOS it can also be installed through the popular package manager Homebrew. For other platforms you download the correct file from the project’s releases page, make it executable, and run the help command to confirm that it works.

The surprise is that OCB itself does not contain a compiler. To compile your distribution, OCB calls the Go toolchain, so Go must be installed on the machine that runs OCB. The project’s repository states which Go versions are compatible, and it is wise to check this before your first build, since a mismatch can produce confusing errors.

Everything OCB does is driven by one small text file, so it pays to understand its parts.

The manifest is a plain text file in a simple, human-readable format. It has a handful of sections. One section, called dist, describes the distribution itself. Several sections list components, one per kind. Two further sections cover where configuration is read from and how modules may be substituted. You only include the sections you need.

A few short fields in this section control how your distribution is named, versioned and written to disk.

Each component in the manifest is identified by where it lives and which version you want.

Every entry under a component section points to a Go module. The entry gives the module’s address, which says where to find it, and a version, which says exactly which release to use. OCB uses these two pieces of information to download the right code. The versions are normally pinned precisely, which means every build with the same manifest produces the same result.

To find the correct address and the available versions, teams use the OpenTelemetry Registry, a searchable catalogue of components. It lists receivers, processors, exporters, extensions and connectors across the ecosystem, with links to their documentation, so you can confirm what a component does and which release matches your Collector version.

The most frequent source of build trouble is mixing pieces that were not designed to work together.

The Collector’s components are released on a regular schedule, and releases of the core program, the builder and the community components are numbered together as a family. A component built against one family of releases expects the core program to behave in a particular way. If you mix releases from distant families, for example a very old component inside a very new core, the pieces may disagree about how they talk to each other. The result can be a build that fails with confusing messages, or worse, a build that succeeds but misbehaves at runtime.

The sensible rule is to keep every version in the manifest, and the builder itself, within the same release family. The builder even performs a check on this by default, and it complains when versions are too far apart. Switching that check off is possible, but it removes a safety net, so it should be done only for a short-lived experiment and never for production.

Let us walk through the complete first build in plain language.

The output folder is not a black box; each file has a clear purpose.

Why the generated source matters

The generated project is useful in three ways. For auditing, a reviewer can read exactly which components and which versions went into a build. For development, an engineer can open the project in a normal Go editor, step through the Collector’s code with a debugger, and see how a component behaves in context. For reproducibility, keeping the manifest and the module files in version control means anyone can rebuild the same distribution later.

A build that compiles is not yet a build that works, so verify before you trust it.

Your custom binary behaves like any other Collector, with a few built-in commands that are very helpful for verification. It can list the components that are compiled into it, which lets you confirm that everything in your manifest made it into the binary and nothing unexpected did. It can also validate a runtime configuration file without starting the pipelines, which catches typing errors and references to components that are not present.

A small manifest section decides how your Collector can read its runtime settings.

When a Collector starts, it needs to find its runtime configuration. Providers are the pieces that know how to fetch it from different places. One provider may read from a file on disk, another from an environment variable, another from a web address, and another from inline text on the command line. In the standard distributions a sensible set of providers is already included, but in a custom distribution you choose which ones to carry.

Sometimes you need to use a component that is not the exact published version, and the replaces section is the escape hatch.

The replaces section lets you tell the build to use a different module, or a different version of a module, than the one that would otherwise be chosen. This is a standard feature of the Go ecosystem, and OCB passes it through. It is useful in a few situations, and risky in all of them if used carelessly.

OCB is not only for assembling existing parts; it is also the fastest way to start writing new ones.

Sometimes the component you need does not exist, perhaps because it talks to an internal system, applies a rule that is specific to your company, or implements an unusual authentication method. You can write your own component in Go. OCB helps because it produces a complete, buildable Collector project around your component, so you can run and debug it inside the real thing from the very first day.

Most Collectors end up in containers, so the build usually continues beyond OCB.

On container platforms you do not copy a binary onto a server; you package it into an image. A common pattern is the multi-stage build. In the first stage, a temporary image contains Go and OCB, and it runs the builder to create the binary. In the final stage, a clean, minimal image receives only the finished binary and the runtime files it needs. The big build tools never reach production, which keeps the final image small and reduces its attack surface.

flowchart LR
    subgraph S1["Stage 1: build image"]
        GO["Go toolchain"] --> OC["OCB runs with manifest"] --> BIN["Binary produced"]
    end
    BIN --> COPY["Copy only the binary"]
    subgraph S2["Stage 2: runtime image"]
        COPY --> RUN["Minimal image with the Collector binary"]
    end
    RUN --> REG["Image registry"]
        

Real fleets are rarely uniform, so a distribution often has to run on more than one kind of machine.

An organisation may run servers with Intel-style processors, newer machines with ARM processors, developer laptops of both kinds, and perhaps some Windows hosts. A custom distribution therefore needs a build for each target. The Go toolchain supports building for a different platform than the one it runs on, and OCB works with this ability, so one pipeline can produce several binaries from one manifest.

A build that only works on one person’s laptop is a risk, so move it into an automated pipeline early.

Continuous integration systems run tasks automatically whenever something changes. For a custom Collector, a pipeline gives you repeatable builds, a visible history, and an easy place to add checks. The manifest lives in version control; every change to it triggers the pipeline; and the pipeline produces a tested, labelled image or binary ready for release.

flowchart LR
    A["Change to manifest in version control"] --> B["Review and approval"]
    B --> C["Pipeline starts"]
    C --> D["Install pinned Go and OCB"]
    D --> E["Run OCB build"]
    E --> F["List components and validate configuration"]
    F --> G["Smoke test and security scan"]
    G --> H["Publish versioned image and records"]
        

The quality of your distribution is decided by what you leave out as much as by what you put in.

A useful way to choose is to work backwards from your pipelines. Start from the runtime configuration you intend to run in production. Every receiver, processor, exporter, extension and connector named there goes into the manifest. Then add the supporting actors that keep the Collector healthy, such as memory protection and health checking. Finally, ask whether any component is there just in case. If so, leave it out; you can always rebuild when a real need arrives.

A smaller distribution is not only tidier; it brings measurable practical advantages.

A binary that contains hundreds of components is larger on disk than one that contains a dozen. Larger files take longer to download, longer to start in a fresh container, and use more storage in image registries and on nodes. Registered components also consume a little memory at startup, even if they are never used. In a large fleet where containers start and stop constantly, these small costs multiply.

The table above is intentionally qualitative, because exact numbers vary with versions, components and platforms. The way to know your own numbers is to build both and measure. Many teams find that the largest gain is not raw speed but the reduction in what needs reviewing and patching.

Choosing fewer components reduces risk, but owning the build also creates responsibilities.

Every component you include is code that runs inside a program that handles sensitive telemetry and often holds credentials. If a flaw is discovered in a component you do not need, but it is present in your binary, you are exposed anyway. By building only what you use, you shrink the number of places where such flaws can lurk. This is the strongest security argument for a custom distribution.

At the same time, once you build your own Collector, you become the one who must notice security fixes and ship them. Ready-made distributions are maintained by others; yours is maintained by you.

A custom distribution is a living thing: it must be rebuilt regularly or it slowly becomes a liability.

The Collector project releases new versions regularly, with new features, fixes and sometimes changes that require attention. A custom distribution does not update itself. Someone must decide when to move to a new release family, update the manifest, rebuild, test and roll out. If this is neglected, the distribution drifts further from upstream, security fixes pile up, and the eventual jump becomes large and risky.

flowchart TD
    A["New release family published"] --> B["Read release notes and deprecations"]
    B --> C["Update builder and all component versions together"]
    C --> D["Rebuild in pipeline"]
    D --> E["Run verification and smoke tests"]
    E --> F["Canary rollout to a small group"]
    F --> G{"Healthy?"}
    G -->|"Yes"| H["Roll out to everyone"]
    G -->|"No"| I["Roll back and investigate"]
        

Let us follow one change all the way from an idea to a running Collector, noting who does what.

sequenceDiagram
    participant D as Developer
    participant R as Repository
    participant P as Pipeline
    participant G as Image registry
    participant K as Cluster
    D->>R: Propose manifest change
    R->>R: Review and approve
    R->>P: Trigger build
    P->>P: Run OCB, verify, scan
    P->>G: Publish versioned image
    P->>K: Roll out to canary
    K-->>P: Health and metrics look good
    P->>K: Roll out to all
        

In an organisation, a shared Collector is a shared product, and shared products need owners and rules.

When several teams use the same custom Collector, questions appear quickly. Who decides which components are allowed? Who responds when a component has a security issue? How does a team request a new integration? Without answers, the manifest either grows without control or becomes a bottleneck that frustrates everyone. A light but clear governance model solves both problems.

Patterns capture what usually works and anti-patterns what usually hurts, and both are cheaper to learn from a page than from an incident.

Patterns that work

Anti-patterns to avoid

A short checklist is often more useful than a long argument.

Examples help the ideas settle, so here are five situations where teams reach for OCB.

OCB is a good answer to some questions and a poor answer to others, so it helps to compare honestly.

Let us design a real distribution on paper, step by step, to see how the reasoning flows.

A company runs a gateway tier that accepts telemetry from many applications using the standard OpenTelemetry protocol, protects itself from overload, adds a label saying which environment the data came from, groups items into efficient batches, and sends everything to a single backend over the same protocol. During testing, engineers also want a debugging output. Operations wants health checks for the container platform and authentication of incoming calls.

A custom build deserves the same testing discipline as any other program you ship.

When something goes wrong, a symptom-first table gets you to the right question quickly.

A calm way to debug a failed build

Once a custom Collector is in production, you need to be able to answer a simple question: what exactly is running here?

With many custom builds in circulation, it quickly becomes difficult to remember which one is deployed where. The remedy is to make every build identify itself. Use the version field in the manifest to give each distribution a meaningful version, label container images with the distribution version and the underlying release family, and keep the bill of materials in a place that engineers can find easily. When someone asks whether a vulnerability affects you, the answer should take minutes, not days.

You do not need to become a Go programmer, but a few Go ideas explain nearly every message OCB shows you.

Go organises code into modules. A module is a folder of code with a name that looks like a web address and a version number such as a release label. When your distribution needs a component, Go finds that component’s module by its address, downloads the requested version, and stores it in a local cache on the build machine. The next build finds it in the cache and does not download it again. This is why the very first build is slow and later ones are quick.

Many organisations do not let build machines reach the open internet, and OCB can still work in those places with some preparation.

OCB needs to download modules, so a build machine that cannot reach the public module services will fail on its first step. Security-conscious organisations solve this in a few well-known ways. All of them move the download from the build machine to a controlled place that your security team can inspect.

Most teams do not start with OCB; they start with an official distribution and migrate when a reason appears.

The safest migration is gradual. You do not need to guess which components you use, because your existing runtime configurations already say so. Every component named in any configuration that runs in production must be in the new manifest. Collect those configurations, list the components they name, and you have the heart of your manifest.

As an organisation grows, one distribution rarely fits every role, and a small family of distributions becomes the natural answer.

Different places in a telemetry system have different needs. A small agent beside an application needs very few components and as little memory as possible. A gateway needs richer processing, authentication and durable queues. A special collector for a particular technology may need an unusual receiver that nobody else wants. Giving each role its own distribution keeps every one of them as small as it can be.

flowchart TD
    M["One repository with several manifests"] --> P["Shared build pipeline"]
    P --> A["Agent distribution"]
    P --> G["Gateway distribution"]
    P --> S["Specialist distribution"]
    P --> D["Development distribution"]
    A --> F1["Agents on every host"]
    G --> F2["Gateway tier"]
    S --> F3["Special use"]
        

A handful of switches change what the produced binary looks like, and it helps to know what each one trades.

A custom distribution is only as useful as the number of people who understand how to use and change it.

A distribution that only one person understands is a risk. Good documentation turns it into a shared tool. The goal is not long documents; it is a few short, honest pages that answer the questions new people ask most often, and that are updated whenever the distribution changes.

A little knowledge of the wiring explains why a missing component stops the Collector at start-up instead of failing quietly later.

Every component in the Collector is created by a small piece of code called a factory. A factory knows the component’s type name, such as the name you write in a runtime configuration, and it knows how to create an instance of the component when the Collector needs it. The generated components file made by OCB collects the factories of every component you listed into registries, one registry for each kind: receivers, processors, exporters, extensions and connectors.

When the Collector starts, it reads the runtime configuration and looks up each named component in the matching registry. If a name is found, the factory builds the component. If a name is not found, the Collector stops immediately with an error saying that the component type is unknown. This early, loud failure is deliberate. It is much better to learn about a missing component at start-up than to discover hours later that a pipeline has been silently doing nothing.

flowchart LR
    M["Manifest: list of components"] --> G["Generated components file"]
    G --> R["Registries: receivers, processors, exporters, extensions, connectors"]
    C["Runtime configuration names a component"] --> L{"Is it in the registry?"}
    R --> L
    L -->|"Yes"| F["Factory creates the component"]
    L -->|"No"| E["Collector stops: unknown component"]
        

A short scoring exercise can turn a vague feeling into a clear decision.

Because a custom distribution brings ongoing work, it deserves a deliberate decision. The table below lists common reasons and the questions that test whether each reason is real. Score each row honestly with a simple yes or no. A single strong yes, with an owner ready to carry the maintenance, is often enough. Several weak yes answers rarely are.

Many of the components you will want come from the wider community, and their quality and upkeep vary.

The core Collector is maintained by the project’s core team, but the large collection of community components is contributed and maintained by many people and companies. Each has its own pace of development and its own stability level, which the documentation states. When you build a custom distribution, you are choosing which of those components your organisation will rely on, so a little due diligence goes a long way.

When you only have a minute, this table recaps the whole journey from idea to running Collector.

A tutorial should be honest about the moving parts, so here is how to stay safe on shifting ground.

The Collector, its builder and its components are actively developed. Names of settings, supported Go versions, installation methods and even the list of official distributions can change between releases. The ideas in this tutorial, choosing components deliberately, keeping versions together, building in a pipeline, verifying before release, and owning upgrades, are lasting. Specific commands and flags are not, so confirm them against the documentation for the exact version you use.

It is a command-line tool that reads a short manifest listing the components you want, generates a small Go project around them, and compiles a custom Collector containing exactly those components.

Not for the standard case of assembling existing components, because you only write a manifest. You need Go installed, since OCB uses it to compile, and Go knowledge only becomes necessary when you write your own components.

You can, and many teams do. A custom distribution is attractive when you want a smaller binary, a smaller attack surface, easier reviews, or a component that is not in any official distribution.

A dist section describing the distribution, lists of receivers, processors, exporters, extensions and connectors with their module addresses and versions, and optionally providers and replacements.

The manifest decides which components exist inside the binary. The runtime configuration decides which of them are used and how when the Collector starts. A component missing from the manifest cannot be used.

Components are built against a particular release family of the core. Mixing families can cause build failures or subtle runtime misbehaviour. Keep the builder, core and components together.

Yes. Write it as a Go module, reference it in the manifest using a local path or replacement during development, and replace that with a pinned published version when it is ready.

Use a multi-stage build: the first stage has Go and OCB and produces the binary, and the final stage is a minimal image that receives only the binary. Match the processor architecture and keep names consistent.

It can be, because fewer components mean fewer places for flaws. But you must also track and ship security fixes yourself, so the benefit only holds if someone owns that work.

On a regular schedule tied to upstream releases, and immediately when a serious security issue affects a component you use. Small, frequent upgrades are easier than large, rare ones.

They let you substitute a different module or version for a component. They are useful for development and urgent fixes, but each one is a fork you own, so record why it exists and remove it when possible.

Ask the binary to list its compiled-in components and compare them with the manifest, validate sample configurations against it, run a smoke test, and keep a bill of materials with each release.

We began with a suitcase packed with everything and a small bag packed with only what the trip needs. The OpenTelemetry Collector Builder lets you choose the small bag. You list the receivers, processors, exporters, extensions and connectors you need in a manifest, pin their versions, and let OCB generate and compile a custom Collector. In return you get a smaller binary, a smaller attack surface, easier reviews, and the freedom to add your own components. In exchange you take on the work of keeping versions aligned, building in a pipeline, verifying every release, scanning for vulnerabilities and upgrading regularly. Done with discipline, a custom distribution is a precise, reviewable tool. Done carelessly, it becomes an unmaintained fork. The difference is not in the tool but in the habits around it.