OpenTelemetry

OpenTelemetry Collector Builder でカスタム Collector をビルドする

必要なコンポーネントをマニフェストに記述し、小さなバイナリやイメージをビルドし、それが割に合うタイミングを知ります。

12 min learn.level.上級

構築済みの Collector のイメージは便利ですが、範囲が広すぎます。contrib ディストリビューションには何百ものコンポーネントが含まれており、そのほとんどは使うことがなく、core ディストリビューションには少なすぎます。より小さなバイナリ、より小さな攻撃対象領域、あるいは自分たち専用のプライベートなコンポーネントが欲しい場合は、OpenTelemetry Collector Builder（ocb）で、必要なものだけを含む Collector を構築できます。入力は 1 つの YAML マニフェストなので、プロセス全体が、設定駆動のままです。

自分で構築するタイミング

使うコンポーネントだけが欲しい。イメージが小さく、パッチを当てる依存関係も減る。
セキュリティポリシーが、ソースからのビルドと、サプライチェーンの制御を要求している。
公式のディストリビューションにない、社内で書かれたようなコンポーネントが必要。

これらのどれも当てはまらない場合は、公式のディストリビューションを使ってください。自分で構築することは、コンポーネントがセキュリティ修正を受けたときに、再ビルドする責任を負うことを意味します。

builder をインストールする

ocb は、Collector の各バージョンとともにリリースされる Go のプログラムです。Collector の GitHub のリリースページからお使いのプラットフォーム向けのバイナリをダウンロードするか、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
  # 任意：ビルド対象の core Collector のバージョン
  # 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 は一緒にリリースされます。すべてを同じリリースに保ってください。バージョンを混在させると、コンパイルエラーになります。
プロバイダーは、どの設定ソースが利用可能かを決めます。${env:VAR} と ${file:/path} を機能させたい場合は、envprovider と fileprovider を含めます。それらがないバイナリは、これらの参照を解決できません。プロバイダーのモジュールは独自のバージョン番号（多くは v1.x）を使うため、ビルド対象のリリースに合わせて調べてください。
コンポーネントのモジュールのパスと名前は変わる可能性があるため、記憶からではなく、各コンポーネントの README や contrib ディストリビューション自身のマニフェストからコピーしてください。

replaces: を使って、モジュールをローカルのフォークに置き換えることができ、gomod のエントリは、自分のプライベートなリポジトリを指せます。

ビルドする

ocb --config builder-config.yaml
# または、go install でインストールした場合：
builder --config builder-config.yaml

出力ディレクトリには、生成された Go のソースコードと、コンパイル済みのバイナリ ./otelcol-custom/otelcol-custom が入ります。通常の設定ファイルで実行し、何が含まれているかを確認します。

./otelcol-custom/otelcol-custom components      # コンパイルされたものを一覧表示
./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 チャート（image.repository と image.tag）または Operator（spec.image）を通じてです。

Helm チャートの preset は、特定のコンポーネントが存在することを前提としていることに注意してください。カスタムのイメージでは、receiver と processor を自分で設定するか、preset が必要とするものがすべて含まれていることを確認してください。

保守可能に保つ

builder-config.yaml を Git に保管し、ノート PC ではなく CI でビルドします。
新しい Collector のリリースが出たとき、または使っているコンポーネントにセキュリティ勧告が影響するときに、再ビルドします。Renovate や Dependabot が、バージョンの文字列を監視できます。
CI で components と、代表的な設定でのスモークテストを実行し、デプロイ前に、欠けているコンポーネントを検出します。
ゼロから積み上げるのではなく、contrib のマニフェストから始めて、使わないものを削除します。

RackMint