Back to Details

otel-collector-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OpenTelemetry Collector Builder (OCB)

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
.
OCB根据一份精确列出所需组件的YAML清单生成并编译自定义Collector二进制文件。权威来源：opentelemetry-collector仓库中的cmd/builder。
当标准
otelcol
/
otelcol-contrib
发行版无法满足需求时，请使用OCB：例如你需要某个未在任何发行版中提供的组件、私有/本地组件，或者仅包含所需组件的轻量化二进制文件。
本技能涵盖发行版构建相关内容。如需配置单个组件，请参考
otel-collector
；如需编写新组件，请查看组件创作指南；如需针对已构建的二进制文件生成测试流量，请参考
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.
  1. 安装OCB：选择与目标Collector版本匹配的OCB版本（详见安装）。
  2. 编写清单 — 包含
    dist:
    块及组件列表。可从最小清单开始；完整配置项参考references/manifest.md。
  3. 版本对齐：所有核心组件共享同一
    v0.x.0
    版本，contrib组件使用相同的
    v0.x.0
    版本，confmap提供程序使用配对的稳定版
    v1.y.0
    。版本不匹配是最常见的构建失败原因 — 详见版本对齐。
  4. 构建：执行
    ocb --config=builder.yaml
    （通过
    go install
    安装时，二进制文件名为
    builder
    ）。CI、Docker、多架构及本地组件构建流程详见references/workflows.md。
  5. 验证：运行
    ./dist/<name> validate --config=<collector-config>.yaml
    ，随后启动服务并发送测试数据（参考
    otel-telemetrygen
    技能）。若构建失败，请查看references/troubleshooting.md。

Install

安装

Pick the OCB version equal to the Collector core version you're targeting.
bash
undefined
选择与目标Collector核心版本一致的OCB版本。
bash
undefined

Release binary (named ocb): https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder

发布版二进制文件（名为ocb）：https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder

Go install (binary is named 
builder
, not 
ocb
):

Go安装方式（二进制文件名为
builder
，而非
ocb
）：

go install go.opentelemetry.io/collector/cmd/builder@v0.158.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 `.`).
go install go.opentelemetry.io/collector/cmd/builder@v0.158.0

以下命令使用发布版归档中的二进制文件名`ocb`。若通过`go install`安装，请将命令中的`ocb`替换为`builder`。

`ocb init`（实验性功能）可在指定`--path`路径（默认当前目录）中快速搭建新的发行版仓库，包含清单、Makefile、示例配置及README。

Minimal manifest

最小清单

yaml
undefined
yaml
undefined

builder.yaml

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.158.0
processors:
  • gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.158.0
exporters:
  • gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.158.0
  • gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.158.0
providers:
  • gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.64.0
  • gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.64.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:

```yaml
processors:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.158.0
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.158.0
processors:
  • gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.158.0
exporters:
  • gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.158.0
  • gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.158.0
providers:
  • gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.64.0
  • gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.64.0

**`providers:`语义说明**：完全省略该配置项将保留OCB内置的默认集合（env、file、http、https、yaml，使用配对的稳定版本）。但一旦设置`providers:`，将**替换**默认集合。生成的Collector会将`conf_resolver.default_uri_scheme`默认设为`env`，因此若显式列表中未包含`envprovider`，除非将其他已包含的提供程序设为默认，否则配置验证将失败。要么完全省略该配置项，要么包含`envprovider`以及Collector配置将使用的所有协议对应的提供程序。

Contrib组件使用相同的列表语法：

```yaml
processors:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.158.0

Version alignment

版本对齐

Two version streams exist and must be paired:
StreamModulesExample
v0.x.0
OCB itself, all core components (
go.opentelemetry.io/collector/...
), all contrib components
v0.158.0
v1.y.0
(stable)		confmap providers (
confmap/provider/...
), other 1.x modules (pdata, etc.)
v1.64.0
Rules:
  • Use the same 
    v0.x.0
     for 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.158.0/cmd/builder/internal/config/default.yaml
    — check it rather than guessing (for 
    v0.158.0
    it is 
    v1.64.0
    ).
  • Versions require the 
    v
    prefix (
    v0.158.0
    , not 
    0.158.0
    ).
  • --skip-strict-versioning
    defaults to 
    true
    , so mismatches surface as Go module resolution errors, not friendly OCB errors. Align versions up front instead of debugging 
    go mod tidy
    output.
存在两个版本流，且必须配对使用：
版本流模块示例
v0.x.0
OCB本身、所有核心组件（
go.opentelemetry.io/collector/...
）、所有contrib组件
v0.158.0
v1.y.0
（稳定版）		confmap提供程序（
confmap/provider/...
）、其他1.x模块（pdata等）
v1.64.0
规则：
  • 所有核心和contrib组件使用相同的
    v0.x.0
    版本    ，且与OCB版本匹配。
  • 对应版本的配对提供程序版本可在该版本的内嵌默认清单中找到权威值：
    https://github.com/open-telemetry/opentelemetry-collector/blob/cmd/builder/v0.158.0/cmd/builder/internal/config/default.yaml
    — 请查看该文件而非猜测（
    v0.158.0
    对应的提供程序版本为
    v1.64.0
    ）。
  • 版本号需包含
    v
    前缀（如
    v0.158.0
    ，而非
    0.158.0
    ）。
  • --skip-strict-versioning
    默认值为
    true
    ，因此版本不匹配会表现为Go模块解析错误，而非友好的OCB错误。建议提前对齐版本，而非调试
    go mod tidy
    的输出。

Build commands and flags

构建命令与参数

bash
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
FlagDefaultPurpose
--config
embedded default manifestManifest path. With no 
--config
, OCB builds 
otelcorecol
, a minimal test-only distribution.
--skip-generate
false
Don't regenerate Go sources
--skip-compilation
false
Generate sources, don't compile
--skip-get-modules
false
Don't run 
go mod tidy
/downloads. Since v0.154.0 also leaves 
go.mod
unregenerated.
--skip-strict-versioning
true
Set to 
false
to make OCB verify resolved versions against the manifest
--ldflags
/ 
--gcflags
—Extra 
go build
flags
--verbose
false
Log the underlying Go commands
Generated output in 
output_path
: 
main.go
, 
components.go
, 
main_others.go
, 
main_windows.go
, 
go.mod
, 
go.sum
, and the compiled binary named 
dist.name
. By default binaries are stripped (
-s -w
); set 
dist.debug_compilation: true
for Delve-friendly builds.
bash
ocb --config=builder.yaml                                  # 完整构建：生成代码 + go mod tidy + 编译
ocb --config=builder.yaml --skip-compilation               # 仅生成源码（适用于两阶段CI构建）
ocb --config=builder.yaml --skip-generate --skip-get-modules  # 编译预先生成的源码，不做修改
参数默认值用途
--config
内嵌默认清单清单路径。若不指定
--config
，OCB将构建
otelcorecol
，一个仅用于测试的最小发行版。
--skip-generate
false
不重新生成Go源码
--skip-compilation
false
生成源码，但不编译
--skip-get-modules
false
不执行
go mod tidy
/模块下载。从v0.154.0版本开始，还会保留
go.mod
不重新生成。
--skip-strict-versioning
true
设置为
false
可让OCB验证解析后的版本与清单是否一致
--ldflags
/ 
--gcflags
—额外的
go build
参数
--verbose
false
记录底层执行的Go命令
生成的输出文件位于
output_path
目录：
main.go
、
components.go
、
main_others.go
、
main_windows.go
、
go.mod
、
go.sum
，以及名为
dist.name
的编译后的二进制文件。默认情况下二进制文件会被剥离调试信息（
-s -w
）；若需支持Delve调试，请设置
dist.debug_compilation: true
。

Reference files

参考文档

  • references/manifest.md — every manifest key: 
    dist:
    fields, component spec (
    gomod
    /
    import
    /
    name
    /
    path
    ), providers, 
    replaces
    , 
    excludes
    , 
    conf_resolver
    , 
    telemetry
  • references/workflows.md — local component development, CI two-stage builds, Docker and multi-arch builds, relationship to 
    opentelemetry-collector-releases
  • references/troubleshooting.md — version mismatches, module conflicts, CGO, missing providers, runtime failures
  • references/manifest.md — 所有清单配置项：
    dist:
    字段、组件规格（
    gomod
    /
    import
    /
    name
    /
    path
    ）、提供程序、
    replaces
    、
    excludes
    、
    conf_resolver
    、
    telemetry
  • references/workflows.md — 本地组件开发、CI两阶段构建、Docker与多架构构建、与
    opentelemetry-collector-releases
    的关系
  • references/troubleshooting.md — 版本不匹配、模块冲突、CGO、缺失提供程序、运行时故障