otel-collector-builder

OpenTelemetry Collector Builder（OCB）

OCB は、含めるコンポーネントを正確に列挙した YAML マニフェストから、カスタム Collector バイナリを生成してコンパイルします。信頼できる情報源：cmd/builder（opentelemetry-collector 内）。

標準の otelcol／otelcol-contrib ディストリビューションでは要件を満たせない場合に OCB を使用します。どのディストリビューションにも含まれないコンポーネント、プライベートまたはローカルのコンポーネントが必要な場合や、実行するコンポーネントだけを含むスリムなバイナリが必要な場合に適しています。

このスキルではディストリビューションのビルドについて説明します。個々のコンポーネントの設定については otel-collector を、新しいコンポーネントの作成についてはコンポーネント作成ガイドを、ビルドしたバイナリに対するテストトラフィックの生成については otel-telemetrygen を参照してください。

ワークフロー

1. OCB をインストールする — 対象とする Collector のバージョンに一致するバージョンを選びます（インストールを参照）。
2. マニフェストを作成する — dist: ブロックとコンポーネントリストを記述します。最小限のマニフェストを出発点にしてください。キーの詳細はreferences/manifest.mdを参照してください。
3. バージョンを揃える。 すべてのコアコンポーネントは同じ v0.x.0 バージョンを使用し、contrib コンポーネントも同じ v0.x.0 を使用します。また、confmap プロバイダーはペアとなる安定版の v1.y.0 を使用します。ここを間違えるとビルド失敗の最大の原因になります。バージョンの整合を参照してください。
4. ビルドする — ocb --config=builder.yaml を実行します（go install でインストールした場合、バイナリ名は builder です）。CI、Docker、マルチアーキテクチャ、ローカルコンポーネントのワークフローについてはreferences/workflows.mdを参照してください。
5. 検証する：./dist/<name> validate --config=<collector-config>.yaml を実行し、その後起動してテストデータを送信します（otel-telemetrygen スキル）。ビルドに失敗した場合はreferences/troubleshooting.mdを参照してください。

インストール

対象とする Collector コアのバージョンと同じ OCB バージョンを選んでください。日付付きの記録に、バイナリが提供されているリリースが記載されています。

# Release binary (named ocb): https://github.com/open-telemetry/opentelemetry-collector-releases/releases?q=cmd/builder
# Go install (binary is named `builder`, not `ocb`):
go install go.opentelemetry.io/collector/cmd/[email protected]

以下のコマンドでは、リリースアーカイブ内のバイナリ名である ocb を使用しています。 go install でインストールした場合は、同じコマンドを builder ... として実行してください。

ocb init（試験的機能）は、新しいディストリビューションリポジトリ（マニフェスト、Makefile、サンプル設定、README）を --path（デフォルトは .）にひな形として生成します。

最小限のマニフェスト

# builder.yaml
dist:
  name: otelcol-custom
  description: Custom OpenTelemetry Collector distribution
  output_path: ./dist
  version: 1.0.0

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

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

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

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

providers: の仕様。 このキーを省略すると、OCB の組み込みのデフォルトセット（ペアとなる安定版の env、file、http、https、yaml）が維持されます。ただし、providers: を設定すると、そのセットは置き換えられます。生成された Collector は conf_resolver.default_uri_scheme のデフォルトを env に設定するため、envprovider を含めず、別の含まれるプロバイダーをデフォルトとして設定しない場合、明示的なリストでは設定の検証に失敗します。キーを省略するか、envprovider と Collector の設定で使用するすべてのスキームを含めてください。

contrib コンポーネントも同じリスト構文を使用します。

processors:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.163.0

バージョンの整合

バージョン系列は3つあり、互いに対応させる必要があります。

系列	モジュール
v0.x.0	OCB 自体、すべてのコアコンポーネント（go.opentelemetry.io/collector/...）、contrib の contrib-base モジュールセット内の contrib コンポーネント
v1.y.0（安定版）	confmap プロバイダー（confmap/provider/...）、その他の 1.x モジュール（pdata など）
contrib v1.x（安定版）	contrib の stable-base モジュールセット内の contrib モジュール（例：processor/k8sattributesprocessor）

2026-10-25 時点で確認済み

オフラインで確認した日付としてこの日付を記載し、値を「現在の最新版」とは決して呼ばないでください。デプロイ前に根拠資料と照合してください。このスキルの例では、v0.163.0 の行を固定しています。OCB、core、contrib-base のコンポーネントにはリリースバージョンを使用します。どちらの行も Go 1.26 以降が必要です。

リリース	Providers（core stable）	Contrib stable-base（k8sattributesprocessor）	ビルド済み OCB バイナリとイメージ
v0.163.0（2026-10-14 にタグ付け）	v1.69.0	v1.2.0	0.163.0～0.163.2 として公開（同一ソース）
v0.162.0	v1.68.0	v1.1.0	公開済み

各タグでの根拠資料：cmd/builder/internal/config/default.yaml にある providers（正式な参照元）、core と contrib の versions.yaml、cmd/builder/go.mod、collector-releases、Docker Hub。

ルール：

• OCB のバージョンに合わせ、すべての core と contrib のコンポーネントに**同じ v0.x.0**を使用します。ただし、対応するタグの contrib の versions.yaml で stable-base セットに含まれる contrib モジュールは例外です。そのセットの v1.x バージョンを使用し、v0.x.0 は使用しないでください（そのタグは存在しません）。同じリリースの otelcol-contrib マニフェストで、このバージョンの組み合わせを確認できます。
• providers は推測せず、リリースに同梱されている default.yaml を参照してください。
• バージョンには v 接頭辞が必要です（0.163.0 ではなく v0.163.0）。
• --skip-strict-versioning のデフォルトは true なので、不一致はわかりやすい OCB エラーではなく、Go モジュールの解決エラーとして表面化します。go mod tidy の出力をデバッグするのではなく、あらかじめバージョンを揃えてください。

ビルドコマンドとフラグ

ocb --config=builder.yaml                                  # full build: generate + go mod tidy + compile
ocb --config=builder.yaml --skip-compilation               # generate sources only (two-stage CI)
ocb --config=builder.yaml --skip-generate --skip-get-modules  # compile pre-generated sources untouched

フラグ	デフォルト	用途
--config	埋め込みのデフォルトマニフェスト	マニフェストのパスです。--config を指定しない場合、OCB は最小限のテスト専用ディストリビューションである otelcorecol をビルドします。
--skip-generate	false	Go ソースを再生成しません
--skip-compilation	false	ソースを生成しますが、コンパイルしません
--skip-get-modules	false	go mod tidy やダウンロードを実行しません。v0.154.0 以降では、go.mod も再生成されません。
--skip-strict-versioning	true	false に設定すると、解決されたバージョンをマニフェストと照合するよう OCB に指示します
--ldflags / --gcflags	—	追加の go build フラグ
--verbose	false	内部で実行される Go コマンドをログに記録します

output_path に生成される出力：main.go、components.go、main_others.go、main_windows.go、go.mod、go.sum、および dist.name という名前のコンパイル済みバイナリ（Windows ターゲットでは .exe が追加されます）。デフォルトではバイナリはストリップされます（-s -w）。Delve でデバッグしやすいビルドにするには、dist.debug_compilation: true を設定してください。

参考ファイル

• references/manifest.md — マニフェストのすべてのキー：dist: フィールド、コンポーネント仕様（gomod／import／name／path）、providers、replaces、excludes、conf_resolver、telemetry
• references/workflows.md — ローカルでのコンポーネント開発、CI の 2 段階ビルド、Docker とマルチアーキテクチャビルド、opentelemetry-collector-releases との関係
• references/troubleshooting.md — バージョンの不一致、モジュールの競合、CGO、providers の不足、実行時の障害