自定义 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——DataKit 已内置 OTLP 接收与常见采集能力。
什么时候需要自定义 Collector？
三种典型场景：
- 组件裁剪：只需要 contrib 中的两三个组件，不想带上全部 100+ 组件的体积与依赖；
- 自研组件：企业内部开发了私有 receiver/exporter（如对接内部系统），需要打进二进制；
- 合规审计：安全要求严格的环境需要明确二进制中到底包含哪些代码。
如果只是常规 OTLP 收发与常见加工，官方发行版足够；若目标后端是观测云，DataKit 通常能直接替代整条管道。
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 版本节奏定期重建，获取安全修复。
观测云视角：什么时候可以跳过自建
自建 Collector 的成本 = 构建维护 + 升级跟进 + 部署运维。观测云用户可以先评估 DataKit：
| 需求 | 自建 Collector | DataKit |
|---|---|---|
| OTLP 接收 | 需部署配置 | 内置（4317/4318） |
| 主机/容器/K8s 采集 | 需配 receivers | 内置采集器一键开启 |
| 日志采集与解析 | filelog + 配置 | 采集 + Pipeline 图形化 |
| 脱敏/过滤 | processors 配置 | Pipeline 函数脚本 |
| 到观测云的投递 | 配 OTLP exporter | 原生 |
只有当你有观测云生态之外的特定组件需求（如某个冷门 receiver）时，才值得走 OCB 自建，并把出口指向观测云。
常见问题（FAQ）
Q：OCB 和官方 contrib 镜像怎么选？ 组件需求在 10 个以内且追求最小化时用 OCB；图省事、测试环境或组件需求杂时用 contrib；生产核心链路建议 OCB 定制。
Q：自定义组件能同时含 connector 和 extension 吗？ 可以，manifest 有对应的 connectors、extensions 段，按需声明即可。
Q：版本不匹配会有什么症状？ 构建时报 API 编译错误，或运行时组件行为异常。OCB 版本与组件版本必须配套。
Q：自定义 Collector 能上报观测云吗？ 可以，exporter 配 otlp 指向 DataKit 的 4317（gRPC）或 4318（HTTP）端点即可。
