otel-collector-builder
Build custom OpenTelemetry Collector distributions with OCB (OpenTelemetry Collector Builder). Use when authoring or debugging a builder manifest (builder.yaml), choosing component and provider versions, building a collector that bundles a custom or out-of-distribution component, setting up CI or Docker builds of a distribution, or troubleshooting OCB build failures. Triggers on "ocb", "collector builder", "custom collector distribution", "builder manifest", "builder-config", and version-mismatch errors from OCB builds.
ollygarden · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ollygarden/opentelemetry-agent-skills --skill otel-collector-builder技能说明
name: otel-collector-builder description: Build custom OpenTelemetry Collector distributions with OCB (OpenTelemetry Collector Builder). Use when authoring or debugging a builder manifest (builder.yaml), choosing component and provider versions, building a collector that bundles a custom or out-of-distribution component, setting up CI or Docker builds of a distribution, or troubleshooting OCB build failures. Triggers on "ocb", "collector builder", "custom collector distribution", "builder manifest", "builder-config", and version-mismatch errors from OCB builds.
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
- Install OCB at the version matching your target Collector version (see Install).
- Write the manifest —
dist:block plus component lists. Start from the minimal manifest; full key reference in references/manifest.md. - Align versions. All core components share one
v0.x.0version, contrib components use the samev0.x.0, and confmap providers use the paired stablev1.y.0. Getting this wrong is the #1 build failure — see Version alignment. - Build with
ocb --config=builder.yaml(binary is namedbuilderwhen installed viago install). CI, Docker, multi-arch, and local-component workflows are in references/workflows.md. - Verify: run
./dist/<name> validate --config=<collector-config>.yaml, then start it and send test data (otel-telemetrygenskill). If the build fails, see references/troubleshooting.md.
Install
Pick the OCB version equal to the Collector core version you're targeting.
# Release binary (named ocb): https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder
# Go install (binary is named `builder`, not `ocb`):
go install go.opentelemetry.io/collector/cmd/builder@v0.160.0
The commands below use ocb, the release-archive binary name. If you install with
go install, invoke the same commands as builder ... instead.
ocb init (experimental) scaffolds a new distribution repo — manifest, Makefile, sample config, README — in --path (default .).
Minimal manifest
# builder.yaml
dist:
name: otelcol-custom
description: Custom OpenTelemetry Collector distribution
output_path: ./dist
version: 1.0.0
receivers:
- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.160.0
processors:
- gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.160.0
exporters:
- gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.160.0
- gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.160.0
providers:
- gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.66.0
- gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.66.0
providers: semantics. Omitting the key entirely keeps OCB's built-in default set (env, file, http, https, yaml at the paired stable version). But setting providers: at all replaces that set. The generated Collector defaults conf_resolver.default_uri_scheme to env, so an explicit list without envprovider fails configuration validation unless you set another included provider as the default. Either omit the key, or include envprovider plus every scheme the collector's config will use.
Contrib components use the same list syntax:
processors:
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.160.0
Version alignment
Two version streams exist and must be paired:
| Stream | Modules | Example |
|---|---|---|
v0.x.0 | OCB itself, all core components (go.opentelemetry.io/collector/...), all contrib components | v0.160.0 |
v1.y.0 (stable) | confmap providers (confmap/provider/...), other 1.x modules (pdata, etc.) | v1.66.0 |
Rules:
- Use the same
v0.x.0for every core and contrib component, matched to the OCB version. - The paired provider version for a given release is authoritative in that release's embedded default manifest:
https://github.com/open-telemetry/opentelemetry-collector/blob/cmd/builder/v0.160.0/cmd/builder/internal/config/default.yaml— check it rather than guessing (forv0.160.0it isv1.66.0). - Versions require the
vprefix (v0.160.0, not0.160.0). --skip-strict-versioningdefaults totrue, so mismatches surface as Go module resolution errors, not friendly OCB errors. Align versions up front instead of debugginggo mod tidyoutput.
Build commands and flags
ocb --config=builder.yaml # full build: generate + go mod tidy + compile
ocb --config=builder.yaml --skip-compilation # generate sources only (two-stage CI)
ocb --config=builder.yaml --skip-generate --skip-get-modules # compile pre-generated sources untouched
| Flag | Default | Purpose |
|---|---|---|
--config | embedded default manifest | Manifest path. With no --config, OCB builds otelcorecol, a minimal test-only distribution. |
--skip-generate | false | Don't regenerate Go sources |
--skip-compilation |