OpenTelemetry Collector Builderを使用してカスタムコレクターをビルドする

OpenTelemetry Collectorには、特定のコンポーネントが事前に構成された5つの公式ディストリビューションがあります。 より柔軟性が必要な場合は、OpenTelemetry Collector Builder（またはocb）を使用して、カスタムコンポーネント、アップストリームコンポーネント、およびほかの公開されている利用可能なコンポーネントを含む独自のディストリビューションのカスタムバイナリを生成できます。

次のガイドでは、ocbを使用して独自のコレクターをビルドする方法を説明します。 この例では、カスタムコンポーネントの開発とテストをサポートするコレクターディストリビューションを作成します。 任意のGolang統合開発環境（IDE）でコレクターコンポーネントを直接起動およびデバッグできます。 IDEのすべてのデバッグ機能（スタックトレースは素晴らしい教師です！）を使用して、コレクターがコンポーネントコードとどのように対話するかを理解します。

前提条件

ocbツールは、コレクターのディストリビューションをビルドするためにGoを必要とします。 開始する前に、マシンに互換性のあるバージョンのGoがインストールされていることを確認してください。

OpenTelemetry Collector Builderのインストール

ocbバイナリは、OpenTelemetry Collectorのcmd/builderタグが付いたリリースからダウンロード可能なアセットとして入手できます。 オペレーティングシステムとチップセットに適したアセットを見つけてダウンロードしてください。

• Linux (AMD 64)
• Linux (ARM 64)
• Linux (ppc64le)
• macOS (AMD 64)
• macOS (ARM 64)
• Windows (AMD 64)

curl --proto '=https' --tlsv1.2 -fL -o ocb \
https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.144.0/ocb_0.144.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.144.0/ocb_0.144.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.144.0/ocb_0.144.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.144.0/ocb_0.144.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.144.0/ocb_0.144.0_darwin_arm64
chmod +x ocb

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

ocbが正しくインストールされたことを確認するには、ターミナルで./ocb helpと入力します。 コマンドのhelp出力がコンソールに表示されるはずです。

OpenTelemetry Collector Builderの構成

YAMLマニフェストファイルで、ocbを構成します。 マニフェストには2つの主要なセクションがあります。 1つ目のセクションであるdistには、コード生成とコンパイルプロセスの構成オプションが含まれています。 2つ目のセクションには、extensions、exporters、receivers、processorsなどのトップレベルのモジュールタイプが含まれています。 それぞれのモジュールタイプは、コンポーネントのリストを受け付けます。

マニフェストのdistセクションには、ocbコマンドラインのflagsに相当するタグが含まれています。 次の表は、distセクションの構成オプションを示しています。

すべてのdistタグはオプションです。 カスタムコレクターディストリビューションを他のユーザーが利用できるようにするか、またはocbを使用してコンポーネント開発およびテスト環境をブートストラップするかに応じて、それらのカスタム値を追加できます。

ocbを構成するには、次の手順に従います。

1. 次の内容でbuilder-config.yamlという名前のマニフェストファイルを作成します。

   dist:
     name: otelcol-dev
     description: 開発者向けの基本的なOTelコレクターのディストリビューション
     output_path: ./otelcol-dev
   

2. カスタムコレクターディストリビューションに含めるコンポーネントのモジュールを追加します。 さまざまなモジュールとコンポーネントの追加方法については、ocb構成ドキュメントを参照してください。

   この例のディストリビューションには、次のコンポーネントを追加します。

   • エクスポーター: OTLPとDebug
   • レシーバー: OTLP
   • プロセッサー: Batch

   builder-config.yamlマニフェストファイルは次のようになります。

   dist:
     name: otelcol-dev
     description: 開発者向けの基本的なOTelコレクターのディストリビューション
     output_path: ./otelcol-dev
   
   exporters:
     - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.144.0
     - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.144.0
   
   processors:
     - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.144.0
   
   receivers:
     - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.144.0
   
   providers:
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/envprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/fileprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/httpprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.48.0
     - gomod:
         go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.48.0
   

コードを生成し、コレクターディストリビューションをビルドする

ocbがインストールおよび構成されたので、ディストリビューションをビルドする準備ができました。

ターミナルで次のコマンドを入力して、ocbを起動します。

./ocb --config builder-config.yaml

コマンドの出力は次のようになります。

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

マニフェストのdistセクションで定義されているように、現在、コレクターディストリビューションのすべてのソースコードとバイナリを含むotelcol-devという名前のフォルダーがあります。

フォルダ構成は次のようになります。

.
├── 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

生成されたコードを使用して、コンポーネント開発プロジェクトをブートストラップし、これらのコンポーネントを使用して独自のコレクターディストリビューションをビルドおよび配布できます。

コレクターディストリビューションのコンテナ化

カスタムコレクターをコンテナ化するには、次のステップに従います。

1. プロジェクトに2つの新しいファイルを追加します。

   • Dockerfile - コレクターのディストリビューションのコンテナイメージ定義
   • collector-config.yaml - ディストリビューションをテストするための最小限のコレクター構成YAML

   これらのファイルを追加した後、ファイルは次のようになります。

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

2. 次の内容をDockerfileに追加します。 この定義は、コレクターのディストリビューションをインプレースでビルドし、生成されたコレクターディストリビューションバイナリがターゲットコンテナアーキテクチャ（たとえば、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.144.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
   

3. 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]
   

4. 次のコマンドを使用して、linux/amd64とlinux/arm64をターゲットビルドアーキテクチャとして使用して、ocbのマルチアーキテクチャDockerイメージをビルドします。 より詳しくは、マルチアーキテクチャビルドに関するこのブログ記事をご覧ください。

   # Dockerマルチアーキテクチャビルドを有効にする
   docker run --rm --privileged tonistiigi/binfmt --install all
   docker buildx create --name mybuilder --use
   
   # DockerイメージをLinux AMDおよびARMとしてビルドし、ビルド結果を「docker images」にロードします
   docker buildx build --load \
     -t <collector_distribution_image_name>:<version> \
     --platform=linux/amd64,linux/arm64 .
   
   # 新たにビルドされたイメージをテストします
   docker run -it --rm -p 4317:4317 -p 4318:4318 \
       --name otelcol <collector_distribution_image_name>:<version>
   

さらなる学びのために

• レシーバーをビルドする
• コネクターをビルドする