自定义 OpenTelemetry Collector：用 OCB 构建专属发行版
当官方 Collector 发行版组件过多或缺少所需组件时，可以用 OCB（OpenTelemetry Collector Builder）按需构建只含所需 Receiver/Processor/Exporter 的自定义发行版。本文讲解 manifest 结构与构建流程，以及与观测云 DataKit 的取舍建议。
OCB（OpenTelemetry Collector Builder）是官方提供的构建工具，通过一份 YAML manifest 声明所需组件，编译生成只包含这些组件的自定义 Collector 二进制——官方 core 版组件有限、contrib 版又过于臃肿（上百个组件带来体积与安全面），自定义构建正是两者之间的平衡点。
核心要点速览
- 何时需要自定义：需要 contrib 中的个别组件、需要自研组件、或要最小化体积与攻击面；
- 核心流程：写 manifest（声明 gomod 依赖的组件列表）→ OCB 生成 Go 工程 → 编译二进制 → 打 Docker 镜像；
- 组件版本要对齐，避免混用不兼容版本；
什么时候需要自定义 Collector？
三种典型场景：
- 组件裁剪：只需要 contrib 中的两三个组件，不想带上全部 100+ 组件的体积与依赖；
- 自研组件：企业内部开发了私有 receiver/exporter（如对接内部系统），需要打进二进制；
- 合规审计：安全要求严格的环境需要明确二进制中到底包含哪些代码。
如果所需组件已包含在官方发行版中，可以先使用该发行版。仅需向观测云发送应用遥测时，可先检查 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.xx.0
processors:
- gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.xx.0
exporters:
- gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.xx.0
要点：
- 每个组件通过
gomod声明 Go module 路径与版本； providers段可自定义配置来源（file/env 等）；- 所有组件版本建议对齐同一 Collector 版本，避免 API 不兼容。
构建流程
# 安装与 manifest 中组件版本对齐的 OCB
go install go.opentelemetry.io/collector/cmd/builder@latest
# 生成代码并编译
ocb --config manifest.yaml
多阶段 Dockerfile 模式：第一阶段复制 manifest 并运行 builder，第二阶段把编译出的二进制与运行时配置拷入精简镜像（如 distroless），暴露 4317/4318 端口即可。
生产使用建议
- 把构建纳入 CI：manifest 进版本库，构建产物可追溯；
- 最小权限：镜像用非 root 运行，只开必要端口；
- 自监控：开启 Collector 自身遥测（internal telemetry），把自身指标也上报（见《监控 OpenTelemetry Collector》）；
- 升级策略：跟随 Collector 版本节奏定期重建，获取安全修复。
常见问题（FAQ）
Q：OCB 和官方 contrib 镜像怎么选？ 组件需求在 10 个以内且追求最小化时用 OCB；图省事、测试环境或组件需求杂时用 contrib；生产核心链路建议 OCB 定制。
Q：自定义组件能同时含 connector 和 extension 吗？ 可以，manifest 有对应的 connectors、extensions 段，按需声明即可。
Q：版本不匹配会有什么症状？ 构建时报 API 编译错误，或运行时组件行为异常。OCB 版本与组件版本必须配套。
Q：自定义 Collector 能上报观测云吗？ 可以先在 DataKit 启用 OpenTelemetry 采集器，再按实际监听地址配置 Collector exporter。gRPC 使用 otlp，HTTP 使用 otlphttp；核对协议、端口和网络连通性后，用测试数据验证接收，参见接入文档。
