构建自定义 Collector

组装您自己的 OpenTelemetry Collector 分发版

如果您计划构建和调试自定义 collector 接收器、处理器、扩展或导出器，您将需要自己的 Collector 实例。这将允许您直接在您喜欢的 Golang IDE 中启动和调试您的 OpenTelemetry Collector 组件。

以这种方式处理组件开发的另一个有趣方面是，您可以使用 IDE 的所有调试功能（堆栈跟踪是很好的老师！）来了解 Collector 本身如何与您的组件代码进行交互。

OpenTelemetry 社区开发了一个名为 OpenTelemetry Collector builder（或简称 ocb）的工具，以协助人们组装自己的分发版，轻松构建包含其自定义组件以及公开可用组件的分发版。

作为该过程的一部分，ocb 将生成 Collector 的源代码，您可以使用这些源代码来帮助构建和调试您自己的自定义组件，让我们开始吧。

步骤 1 - 安装构建器

ocb 二进制文件可作为 OpenTelemetry Collector releases with cmd/builder tags 的可下载资产。您会找到基于操作系统和芯片组命名的资产列表，请下载适合您配置的资产。

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.142.0/ocb_0.142.0_linux_amd64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.142.0/ocb_0.142.0_linux_arm64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.142.0/ocb_0.142.0_linux_ppc64le
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.142.0/ocb_0.142.0_darwin_amd64
chmod +x ocb

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.142.0/ocb_0.142.0_darwin_arm64
chmod +x ocb

Invoke-WebRequest -Uri "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.142.0/ocb_0.142.0_windows_amd64.exe" -OutFile "ocb.exe"
Unblock-File -Path "ocb.exe"

为确保 ocb 已准备好使用，请打开终端并输入 ./ocb help，回车后您应该会在控制台中看到 help 命令的输出。

步骤 2 - 创建构建器清单文件

构建器的 manifest 文件是一个 yaml 文件，您可以在其中传递有关代码生成和编译过程的信息，以及您希望添加到 Collector 分发版中的组件。

manifest 以一个名为 dist 的映射开始，该映射包含用于帮助您配置代码生成和编译过程的标签。事实上，dist 的所有标签都等同于 ocb 命令行 flags。

以下是 dist 映射的标签

Tag描述Optional默认值
module新分发版的模块名称，遵循 Go mod 约定。可选，但推荐。是go.opentelemetry.io/collector/cmd/builder
name您的分发版的二进制文件名称是otelcol-custom
description应用程序的长名称。是自定义 OpenTelemetry Collector 分发版
output_path用于写入输出（源代码和二进制文件）的路径。是/var/folders/86/s7l1czb16g124tng0d7wyrtw0000gn/T/otelcol-distribution3618633831
version您的自定义 OpenTelemetry Collector 的版本。是1.0.0
go用于编译生成的源代码的 Go 二进制文件。是从 PATH 导入 Go

正如您在上面的表中看到的，所有 dist 标签都是可选的，因此您将根据您的意图来添加自定义值，以决定是否使您的自定义 Collector 分发版可供其他用户使用，或者您只是利用 ocb 来引导您的组件开发和测试环境。

在本教程中，您将创建一个 Collector 分发版来支持组件的开发和测试。

请继续创建一个名为 builder-config.yaml 的清单文件，其中包含以下内容

dist:
  name: otelcol-dev
  description: Basic OTel Collector distribution for Developers
  output_path: ./otelcol-dev

现在，您需要添加代表您想要包含在此自定义 Collector 分发版中的组件的模块。请查看 ocb 配置文档，以了解不同的模块以及如何添加组件。

我们将把以下组件添加到我们的开发和测试 collector 分发版中

  • 导出器：OTLP 和 Debug
  • 接收器：OTLP
  • 处理器：Batch

添加组件后，builder-config.yaml 清单文件将如下所示

dist:
  name: otelcol-dev
  description: Basic OTel Collector distribution for Developers
  output_path: ./otelcol-dev

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

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

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

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.18.0

步骤 3a - 生成代码并构建您的 Collector 分发版

现在您只需要让 ocb 完成它的工作，所以请打开终端并输入以下命令

./ocb --config builder-config.yaml

如果一切顺利，命令的输出应该如下所示

2022-06-13T14:25:03.037-0500	INFO	internal/command.go:85	OpenTelemetry Collector distribution builder	{"version": "0.142.0", "date": "2023-01-03T15:05:37Z"}
2022-06-13T14:25:03.039-0500	INFO	internal/command.go:108	Using config file	{"path": "builder-config.yaml"}
2022-06-13T14:25:03.040-0500	INFO	builder/config.go:99	Using go	{"go-executable": "/usr/local/go/bin/go"}
2022-06-13T14:25:03.041-0500	INFO	builder/main.go:76	Sources created	{"path": "./otelcol-dev"}
2022-06-13T14:25:03.445-0500	INFO	builder/main.go:108	Getting go modules
2022-06-13T14:25:04.675-0500	INFO	builder/main.go:87	Compiling
2022-06-13T14:25:17.259-0500	INFO	builder/main.go:94	Compiled	{"binary": "./otelcol-dev/otelcol-dev"}

如您的配置文件 dist 部分所述，您现在有了一个名为 otelcol-dev 的文件夹，其中包含您的 Collector 分发版的所有源代码和二进制文件。

文件夹结构应如下所示

.
├── builder-config.yaml
├── ocb
└── otelcol-dev
    ├── components.go
    ├── components_test.go
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── main_others.go
    ├── main_windows.go
    └── otelcol-dev

您现在可以使用生成的代码来引导您的组件开发项目，并轻松构建和分发包含您组件的 collector 分发版。

步骤 3b - 容器化您的 Collector 分发版

您需要向您的项目添加两个新文件

  • Dockerfile - 您的 Collector 分发版的容器镜像定义
  • collector-config.yaml - 用于测试您的分发版的最小 Collector 配置 YAML

添加这些文件后，您的文件结构看起来如下

.
├── builder-config.yaml
├── collector-config.yaml
└── Dockerfile

以下 Dockerfile 会就地构建您的 Collector 分发版，确保生成的 Collector 分发版二进制文件与目标容器架构匹配（例如 linux/arm64、linux/amd64）。

FROM alpine:3.19 AS certs
RUN apk --update add ca-certificates

FROM golang:1.25.0 AS build-stage
WORKDIR /build

COPY ./builder-config.yaml builder-config.yaml

RUN --mount=type=cache,target=/root/.cache/go-build GO111MODULE=on go install go.opentelemetry.io/collector/cmd/builder@v0.142.0
RUN --mount=type=cache,target=/root/.cache/go-build builder --config builder-config.yaml

FROM gcr.io/distroless/base:latest

ARG USER_UID=10001
USER ${USER_UID}

COPY ./collector-config.yaml /otelcol/collector-config.yaml
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
COPY --chmod=755 --from=build-stage /build/otelcol-dev /otelcol

ENTRYPOINT ["/otelcol/otelcol-dev"]
CMD ["--config", "/otelcol/collector-config.yaml"]

EXPOSE 4317 4318 12001

以下是最小化的 collector-config.yaml 定义

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

使用以下命令构建 OCB 的多架构 Docker 镜像，将 linux/amd64 和 linux/arm64 作为目标构建架构。要了解更多信息，请参阅这篇关于多架构构建的 博客文章。

# Enable Docker multi-arch builds
docker run --rm --privileged tonistiigi/binfmt --install all
docker buildx create --name mybuilder --use

# Build the Docker image as Linux AMD and ARM,
# and loads the build result to "docker images"
docker buildx build --load \
  -t <collector_distribution_image_name>:<version> \
  --platform=linux/amd64,linux/arm64 .

# Test the newly-built image
docker run -it --rm -p 4317:4317 -p 4318:4318 \
    --name otelcol <collector_distribution_image_name>:<version>

进一步阅读：


最后修改日期：2025 年 12 月 13 日： docs: Create new Extend the Collector section and rename child pages (#8599) (6a7f1745)