OpenTelemetry Collector Builder (OCB)

OCB generates and compiles a custom Collector binary from a YAML manifest that lists exactly the components to include. Source of truth: cmd/builder in opentelemetry-collector.

Use OCB when the stock otelcol/otelcol-contrib distributions don't fit: you need a component that ships in no distribution, a private/local component, or a slimmer binary with only the components you run.

This skill covers building the distribution. For configuring individual components, see otel-collector; for writing a new component, see the component-authoring guidance; for generating test traffic against the built binary, see otel-telemetrygen.

Workflow

1. Install OCB at the version matching your target Collector version (see Install).
2. Write the manifest — dist: block plus component lists. Start from the minimal manifest; full key reference in references/manifest.md.
3. Align versions. All core components share one v0.x.0 version, contrib components use the same v0.x.0, and confmap providers use the paired stable v1.y.0. Getting this wrong is the #1 build failure — see Version alignment.
4. Build with ocb --config=builder.yaml (binary is named builder when installed via go install). CI, Docker, multi-arch, and local-component workflows are in references/workflows.md.
5. Verify: run ./dist/<name> validate --config=<collector-config>.yaml, then start it and send test data (otel-telemetrygen skill). If the build fails, see references/troubleshooting.md.

Install

Pick the OCB version equal to the Collector core version you're targeting.