otel-collector-builder

OpenTelemetry Collector Builder（OCB）

OCB 根据 YAML 清单生成并编译自定义 Collector 二进制文件，清单会精确列出要包含的组件。权威来源：cmd/builder，位于 opentelemetry-collector 中。

如果标准的 otelcol/otelcol-contrib 发行版不符合需求，请使用 OCB：例如需要某个未包含在任何发行版中的组件、私有/本地组件，或者只包含实际运行组件的精简二进制文件。

本技能介绍如何构建发行版。有关单个组件的配置，请参阅 otel-collector；有关编写新组件，请参阅组件编写指南；有关针对构建出的二进制文件生成测试流量，请参阅 otel-telemetrygen。

工作流

1. 安装 OCB，版本需与目标 Collector 版本匹配（参见安装）。
2. 编写清单——包含 dist: 块和组件列表。从最小清单开始；完整的键参考见 references/manifest.md。
3. 对齐版本。 所有核心组件使用相同的 v0.x.0 版本，contrib 组件也使用相同的 v0.x.0，而 confmap provider 使用配对的稳定版 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。

安装

选择与目标 Collector 核心版本相同的 OCB 版本；带日期的记录会显示哪些版本提供了二进制文件。

# 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/[email protected]

以下命令使用 ocb，即发行版归档中的二进制文件名。如果通过 go install 安装，请改用 builder ... 执行相同命令。

ocb init（实验性）会在 --path（默认为 .）指定的位置搭建新的发行版仓库，包含清单、Makefile、示例配置和 README。

最小清单

# 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.163.0

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.163.0

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.163.0
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.163.0

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.69.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.69.0

providers: 语义。 完全省略此键会保留 OCB 内置的默认集合（env、file、http、https、yaml，均使用配对的稳定版本）。但只要设置了 providers:，就会替换该集合。生成的 Collector 会将 conf_resolver.default_uri_scheme 默认设为 env，因此，如果显式列表中没有 envprovider，除非将另一个已包含的 provider 设为默认项，否则配置验证会失败。可以省略此键，也可以加入 envprovider 以及 collector 配置将使用的所有 scheme。

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

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

版本对齐

有三组版本流，必须正确配对：

版本流	模块
v0.x.0	OCB 本身、所有核心组件（go.opentelemetry.io/collector/...）、contrib contrib-base 模块集合中的 contrib 组件
v1.y.0（稳定版）	confmap provider（confmap/provider/...）、其他 1.x 模块（pdata 等）
contrib v1.x（稳定版）	contrib stable-base 模块集合中的 contrib 模块（例如 processor/k8sattributesprocessor）

已验证：2026-10-25

此信息为离线整理，请注明此日期，切勿称任何值为当前最新值，并在部署前根据证据确认。此技能中的示例固定使用 v0.163.0 这一行。OCB、core 和 contrib-base 组件使用发布版本；两行都需要 Go 1.26+。

发布版本	Providers（core stable）	Contrib stable-base（k8sattributesprocessor）	预构建的 OCB 二进制文件和镜像
v0.163.0（标记于 2026-10-14）	v1.69.0	v1.2.0	发布为 0.163.0–0.163.2（同一源代码）
v0.162.0	v1.68.0	v1.1.0	已发布

每个标签对应的证据：providers 见 cmd/builder/internal/config/default.yaml（权威来源），core 和 contrib 的 versions.yaml、cmd/builder/go.mod、collector-releases、Docker Hub。

规则：

• core 和 contrib 的所有组件都使用与 OCB 版本匹配的同一个 v0.x.0，但 contrib 的 versions.yaml 中，匹配标签的 stable-base 集合内的 contrib 模块除外；这些模块应使用该集合的 v1.x 版本，不能使用 v0.x.0（不存在这样的标签）。同一发布版本的 otelcol-contrib 清单中展示了这种对应关系。
• providers 应从该发布版本内嵌的 default.yaml 中获取，不要猜测。
• 版本号必须带 v 前缀（v0.163.0，而非 0.163.0）。
• --skip-strict-versioning 默认值为 true，因此版本不匹配会表现为 Go 模块解析错误，而不是友好的 OCB 错误。请预先对齐版本，不要再调试 go mod tidy 的输出。

构建命令和标志

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

标志	默认值	用途
--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 的已编译二进制文件（Windows 目标会追加 .exe）。默认情况下，二进制文件会被剥离（-s -w）；设置 dist.debug_compilation: true 可构建便于使用 Delve 调试的版本。

参考文件

• references/manifest.md — 清单中的所有键：dist: 字段、组件规格（gomod/import/name/path）、providers、replaces、excludes、conf_resolver、telemetry
• references/workflows.md — 本地组件开发、CI 两阶段构建、Docker 和多架构构建，以及与 opentelemetry-collector-releases 的关系
• references/troubleshooting.md — 版本不匹配、模块冲突、CGO、缺少 providers、运行时故障