カスタムコレクターのビルド

カスタムコレクターのレシーバー、プロセッサー、エクステンション、またはエクスポーターをビルドおよびデバッグする計画がある場合は、独自のコレクターインスタンスが必要になります。 これにより、任意のGolang IDE内でOpenTelemetry Collectorコンポーネントを直接起動およびデバッグできるようになります。

この方法でコンポーネント開発に取り組むもうひとつの興味深い側面は、IDEのすべてのデバッグ機能（スタックトレースは素晴らしい教師です！）を使用して、コレクター自体がコンポーネントのコードとどのように対話するかを理解できることです。

OpenTelemetryコミュニティは、独自のディストリビューションの組み立てを支援するためにOpenTelemetry Collector builder（略してocb）と呼ばれるツールを開発しました。 これにより、公開されているコンポーネントとともにカスタムコンポーネントを含むディストリビューションを簡単にビルドできるようになります。

プロセスの一環として、ocbは独自のカスタムコンポーネントのビルドとデバッグに役立つコレクターのソースコードを生成します。 それでは始めましょう。

ステップ 1 - ビルダーのインストール

ocbバイナリは、OpenTelemetry Collectorのcmd/builderタグが付いたリリースからダウンロード可能なアセットとして入手できます。 OSとチップセットに基づいて名前が付けられたアセットのリストがあるため、ご自身の構成に適したものをダウンロードしてください。

• 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.140.0/ocb_0.140.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.140.0/ocb_0.140.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.140.0/ocb_0.140.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.140.0/ocb_0.140.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.140.0/ocb_0.140.0_darwin_arm64
chmod +x ocb

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

ocbが使用可能であることを確認するには、ターミナルに移動して./ocb helpと入力し、Enterキーを押すとhelpコマンドの出力がコンソールに表示されるはずです。

ステップ 2 - ビルダーマニフェストファイルの作成

ビルダーのmanifestファイルはyamlであり、コード生成とコンパイルプロセスに関する情報と、コレクターのディストリビューションに追加したいコンポーネントを組み合わせて渡します。

manifestは、コード生成とコンパイルプロセスの構成に役立つタグを含むdistという名前のマップで始まります。 実際にdistのすべてのタグは、ocbコマンドラインのflagsに相当します。

distマップのタグは次のとおりです。

上の表からわかるように、すべてのdistタグはオプショナルであるため、カスタムコレクターディストリビューションの利用可能性を他のユーザーに提供する意図があるか、または単にocbを使用してコンポーネントの開発およびテスト環境をブートストラップするだけかに応じて、それらのカスタム値を追加します。

このチュートリアルでは、コンポーネントの開発とテストをサポートするコレクターのディストリビューションを作成します。

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

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

次に、このカスタムコレクターディストリビューションに組み込みたいコンポーネントを表すモジュールを追加する必要があります。 それぞれのモジュールとコンポーネントの追加方法については、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.140.0
  - gomod:
      go.opentelemetry.io/collector/exporter/otlpexporter v0.140.0

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

receivers:
  - gomod:
      go.opentelemetry.io/collector/receiver/otlpreceiver v0.140.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 - コードを生成し、コレクターのディストリビューションをビルドする

必要なのはocbに仕事をさせることだけなので、ターミナルに移動して次のコマンドを入力します。

./ocb --config builder-config.yaml

すべてが順調に進んだ場合、コマンドの出力は次のようになります。

2022-06-13T14:25:03.037-0500	INFO	internal/command.go:85	OpenTelemetry Collector distribution builder	{"version": "0.140.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という名前のフォルダがあります。

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

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

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

ステップ 3b - コレクターのディストリビューションをコンテナ化する

プロジェクトに次の2つの新しいファイルを追加する必要があります。

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

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

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

次の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.140.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]

次のコマンドを使用して、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>

さらなる学びのために

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