OpenTelemetry

使用 OpenTelemetry Collector Builder 构建自定义 Collector

在清单中描述你需要的组件,构建一个小型二进制文件或镜像,并了解何时值得这样做。

12 min 高级

预构建的 Collector 镜像很方便但范围很广。contrib 发行版包含数百个组件,其中大多数你永远用不到,而 core 发行版又太少。如果你想要更小的二进制文件、更小的攻击面,或者你自己的私有组件,你可以用 OpenTelemetry Collector Builder(ocb)精确构建你所需要的 Collector。输入是单个 YAML 清单,所以整个过程仍然是由配置驱动的。

何时构建你自己的

你只想要你所使用的组件,以获得更小的镜像和更少需要打补丁的依赖。
安全策略要求你从源码构建并控制供应链。
你需要一个不在任何官方发行版中的组件,比如内部编写的。

如果这些都不适用,请使用官方发行版。构建你自己的意味着,每当组件收到安全修复时,你都要承担重新构建的工作。

安装 builder

ocb 是一个随每个 Collector 版本发布的 Go 程序。从 Collector 的 GitHub releases 页面下载适合你平台的二进制文件,或者用 Go 安装它:

go install go.opentelemetry.io/collector/cmd/builder@v0.163.0

builder 和组件请使用相同的版本。(所示版本只是示例;请使用当前的发布版本。)运行构建时必须已安装 Go 工具链。请查看 OpenTelemetry 文档中的安装指南,了解确切的二进制文件名称和下载链接,因为它们因版本而异。

编写清单

# builder-config.yaml
dist:
  name: otelcol-custom
  description: Custom OpenTelemetry Collector
  output_path: ./otelcol-custom
  # Optional: the version of the core Collector to build against
  # otelcol_version: 0.163.0

receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.163.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/filelogreceiver v0.163.0

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.163.0
  - gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.163.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/k8sattributesprocessor v0.163.0

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

extensions:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.163.0

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

要点:

每个条目指明一个 Go 模块和一个版本(gomod)。Contrib 组件位于 github.com/open-telemetry/opentelemetry-collector-contrib/... 之下,core 组件位于 go.opentelemetry.io/collector/... 之下。
组件版本必须兼容。 Core 组件、contrib 组件和 builder 是一起发布的;请让它们全部保持在同一个发布版本上。混用版本会导致编译错误。
Provider 决定哪些配置来源可用。如果你希望 ${env:VAR} 和 ${file:/path} 起作用,请包含 envprovider 和 fileprovider。没有它们的二进制文件无法解析这些引用。Provider 模块使用它们自己的版本号(通常是 v1.x),所以请为你构建所针对的发布版本查找它们。
组件的模块路径和名称可能会变化,所以请从每个组件的 README 或 contrib 发行版自己的清单中复制它们,而不是凭记忆。

你可以使用 replaces: 用本地的 fork 来替换某个模块,并且 gomod 条目可以指向你的私有仓库。

构建

ocb --config builder-config.yaml
# or, if installed with go install:
builder --config builder-config.yaml

输出目录包含生成的 Go 源码和一个编译好的二进制文件 ./otelcol-custom/otelcol-custom。用普通的配置文件运行它,并检查包含了什么:

./otelcol-custom/otelcol-custom components      # list what was compiled in
./otelcol-custom/otelcol-custom validate --config=config.yaml
./otelcol-custom/otelcol-custom --config=config.yaml

如果你的配置引用了一个没有被构建进去的组件,Collector 会在启动时失败并指出它。把它添加到清单中并重新构建。

打包为容器镜像

多阶段 Dockerfile 在 Go 镜像中构建,并把结果复制到一个最小的基础镜像中:

FROM golang:1.24 AS build
WORKDIR /src
RUN go install go.opentelemetry.io/collector/cmd/builder@v0.163.0
COPY builder-config.yaml .
RUN CGO_ENABLED=0 builder --config builder-config.yaml

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /src/otelcol-custom/otelcol-custom /otelcol-custom
USER nonroot
ENTRYPOINT ["/otelcol-custom"]
CMD ["--config=/etc/otelcol/config.yaml"]

请使用与 Collector 发布版本要求相匹配的 Go 版本(查看发布说明),并考虑按摘要固定镜像。在 CI 中构建并发布该镜像,并像部署任何官方镜像一样部署它:通过 Helm chart(image.repository 和 image.tag)或 Operator(spec.image)。

请注意,Helm chart 的 preset 假定存在特定的组件。使用自定义镜像时,请自己配置 receiver 和 processor,或者确认 preset 所需的每一个都已被包含。

保持可维护

把 builder-config.yaml 保存在 Git 中,并在 CI 而不是笔记本电脑上构建。
当有新的 Collector 版本发布,或某个安全公告影响了你所使用的某个组件时,重新构建。Renovate 或 Dependabot 可以监视版本字符串。
在 CI 中运行 components 以及用有代表性的配置做的冒烟测试,这样缺失的组件会在部署之前就被发现。
从 contrib 清单开始并移除你不使用的内容,而不是从零开始构建。

RackMint