自定义 OpenTelemetry Collector：用 OCB 构建专属发行版

OCB（OpenTelemetry Collector Builder）是官方提供的构建工具，通过一份 YAML manifest 声明所需组件，编译生成只包含这些组件的自定义 Collector 二进制——官方 core 版组件有限、contrib 版又过于臃肿（上百个组件带来体积与安全面），自定义构建正是两者之间的平衡点。

核心要点速览

• 何时需要自定义：需要 contrib 中的个别组件、需要自研组件、或要最小化体积与攻击面；
• 核心流程：写 manifest（声明 gomod 依赖的组件列表）→ OCB 生成 Go 工程 → 编译二进制 → 打 Docker 镜像；
• 组件版本要对齐，避免混用不兼容版本；

什么时候需要自定义 Collector？

三种典型场景：

1. 组件裁剪：只需要 contrib 中的两三个组件，不想带上全部 100+ 组件的体积与依赖；
2. 自研组件：企业内部开发了私有 receiver/exporter（如对接内部系统），需要打进二进制；
3. 合规审计：安全要求严格的环境需要明确二进制中到底包含哪些代码。

如果所需组件已包含在官方发行版中，可以先使用该发行版。仅需向观测云发送应用遥测时，可先检查 DataKit 的 OpenTelemetry 接收配置是否满足需求；已有 Collector 的处理、路由和队列逻辑仍需逐项评估，不能仅凭支持 OTLP 就认定可替换。

OCB manifest 的结构

manifest 的核心是 dist（发行版元信息）+ 组件清单：

dist:
  name: my-otelcol
  description: 自定义 Collector
  version: 0.1.0
  output_path: ./build

receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.162.0

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

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

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

要点：

• 每个组件通过 gomod 声明 Go module 路径与版本；
• providers 段可自定义配置来源（file/env 等）；
• 组件应采用同一发行版的兼容版本集合，不代表版本字符串必须相同；此例组件为 v0.162.0、配置 provider 为 v1.68.0，dist.version 是自定义发行版本。

构建流程

# 安装与 manifest 中组件版本对齐的 OCB
mkdir -p bin
GOBIN="$PWD/bin" go install go.opentelemetry.io/collector/cmd/builder@v0.162.0

# 生成代码并编译
./bin/builder --config manifest.yaml

多阶段 Dockerfile 模式：第一阶段复制 manifest 并运行 builder，第二阶段把编译出的二进制与运行时配置拷入精简镜像（如 distroless），还需单独的运行时 service.pipelines 配置、接收端监听地址、TLS 证书及必要可写目录；EXPOSE 本身不启用监听或发布端口。

生产使用建议

• 把构建纳入 CI：manifest 进版本库，构建产物可追溯；
• 最小权限：镜像用非 root 运行，只开必要端口；
• 自监控：开启 Collector 自身遥测（internal telemetry），把自身指标也上报（见《监控 OpenTelemetry Collector》）；
• 升级策略：跟随 Collector 版本节奏定期重建，获取安全修复。

常见问题（FAQ）

Q：OCB 和官方 contrib 镜像怎么选？ 依据裁剪收益、自研组件与维护成本选择，没有 10 个组件的技术阈值，生产环境也不必一律定制。

Q：自定义组件能同时含 connector 和 extension 吗？ 可以，manifest 有对应的 connectors、extensions 段，按需声明即可。

Q：版本不匹配会有什么症状？ 构建时报 API 编译错误，或运行时组件行为异常。OCB 版本与组件版本必须配套。

Q：自定义 Collector 能上报观测云吗？ 可以先在 DataKit 启用 OpenTelemetry 采集器，再按实际监听地址配置 Collector exporter。本例版本的 exporter 使用 otlp_grpc（gRPC）或 otlp_http（HTTP），较旧版本使用 otlp/otlphttp，应以所构建组件清单为准；核对协议、端口和网络连通性后，用测试数据验证接收，参见接入文档。

系列阅读

• 上一篇：《OpenTelemetry Collector 详解》
• 下一篇：《OTTL 转换语言详解》
• 相关：《K8s 部署 OpenTelemetry Collector》 · 《返回索引》

[1]: 观测云文档《OpenTelemetry》https://docs.guance.com/integrations/opentelemetry/
[2]: 观测云文档《DataKit》https://docs.guance.com/datakit/