otel-collector

OpenTelemetry Collector

このスキルでは、個々の OpenTelemetry Collector コンポーネントの設定項目を扱います。opentelemetry-collector と opentelemetry-collector-contrib を対象とします。

OTTL 式（otel-ottl を参照）、宣言型 SDK 設定（otel-declarative-config）、eBPF プロファイラーやその他のプロファイル生成コンポーネントのデプロイ（otel-profiles）、エンドツーエンドのパイプライン設計の選択肢は扱いません。変換言語、SDK のセットアップ、パイプラインの構成に関する質問には、それらのスキルを参照してください。

ワークフロー

1. コンポーネントを特定します。 ユーザーの設定または質問にある type を見つけます（log_dedup、interval、otlp、…）。v0.146.0 以降、多くのコンポーネント名が snake_case に変更され、非推奨の別名は引き続き使用できます。最近の名称変更を参照してください。
2. 回答する前にコンポーネントのページを読み込みます。 コンポーネントがコンポーネント一覧にある場合は、必ず最初に components/<type>/README.md を読んでください。トップレベルの一覧は参照先を見つけるためのものであり、回答の根拠としては不十分です。その Details 索引に従い、必要最小限の関連ファイルを確認してください。バージョンごとのキー、デフォルト値、検証については configuration.md、安定性、利用可否、障害時の動作、移行時の注意点については quirks.md を読み、その他の詳細ファイルは質問に応じて確認します。概要の行や記憶だけを根拠に、具体的な設定やステータスを推測しないでください。
3. コンポーネントが一覧にない場合は、その旨を明示します。 opentelemetry-collector-contrib の processor/<name>/、receiver/<name>/、exporter/<name>/、connector/<name>/、または extension/<name>/ にある上流の README を参照します。Collector コンポーネントは急速に進化するため、記憶を頼りに設定キーを作り出さないでください。
4. Collector 全体に適用される規約を適用します。 Collector 全体に適用される規約の名前付きインスタンス（type/name）、安定性レベル、パイプライン配置規則は、すべてのコンポーネントに適用されます。
5. 検証します。 コンポーネントページの Verification 手順を実行します。telemetrygen（otel-telemetrygen スキルを参照）と debug または file エクスポーターを使い、コンポーネントがドキュメントどおりに動作することを確認します。Alpha および Development の安定性レベルにあるコンポーネントはよく使われており、リリースごとに動作が変わります。手順をエンドツーエンドで実行する方法については、検証ハーネスを参照してください。

コンポーネント一覧

各コンポーネントは components/<type>/ 以下のディレクトリにあります。File 列には、簡潔な README.md（メタデータ、説明、主な用途、Details 索引）へのパスが記載されています。完全な設定リファレンス、検証手順、高度なユースケース、注意点は、その README からリンクされている詳細ファイルにあります。

対象範囲は意図的に絞っています。ここに一覧がないコンポーネントについては、ユーザーが使用している Collector のバージョンに対応する上流のコンポーネント README を参照してください。

2026-10-25 に検証済み：ここおよびコンポーネント README のヘッダーにある安定性セルは、core と contrib の v0.163.0 における metadata.yaml と一致しています。名称変更と「since」のバージョンは、記載されたタグおよびその1つ前のタグにおける metadata.yaml と一致しています。オフラインの場合は、現在の安定性ではなく、そのリリースと日付を引用してください。

種類	ファイル	種別	シグナル	安定性	概要
log_dedup	components/log_dedup/README.md	プロセッサー	ログ	Alpha	時間枠内で同一のログレコードを重複排除し、件数を含む集約ログを1件出力します。v0.151.0でlogdedupから名称変更されましたが、エイリアスは維持されています。
interval	components/interval/README.md	プロセッサー	メトリクス	Alpha	メトリクスをバッファリングし、各系列について間隔ごとに1つのデータポイントを出力します。累積単調系列、ゲージ、サマリーでは最新値を、デルタ系列では合計値を出力します。非単調和は変更せずに通過します。
tail_sampling	components/tail_sampling/README.md	プロセッサー	トレース	Beta	トレース全体をバッファリングし、待機時間の経過後にポリシーに基づいて保持または破棄を一度だけ決定します。num_shardsによるプロセス内の並行処理をサポートします。Collectorインスタンス間でスケーリングするには、引き続きload_balancingレイヤーが必要です。v0.160では、レート／バイト数制限向けにtracestate対応のしきい値が追加されました。
drain	components/drain/README.md	プロセッサー	ログ	Alpha	ログ本文をクラスタリングし、各レコードにテンプレートを付与します。v0.158では、名前付き値に対するextract_parameters／params_attributeがmasking_rules＋parameter_key_prefixに、残りの<*>位置に対する設定がemit_wildcards＋wildcards_attributeに置き換えられました。
redaction	components/redaction/README.md	プロセッサー	トレース、ログ、メトリクス	Beta（トレース）、Alpha（ログ／メトリクス）	許可リスト／ブロックリストによるマスキング、または機密性の高い属性キーや値の削除に対応し、ハッシュ化やURL／DBサニタイザーも備えています。
filter	components/filter/README.md	プロセッサー	トレース、メトリクス、ログ、プロファイル	Alpha（トレース／メトリクス／ログ）、Development（プロファイル）	OTTL条件（または従来のメトリクス名／重大度フィルター）に一致するスパン、メトリクスデータポイント、ログレコード、プロファイルを破棄します。テレメトリ量を最も直接的に調整できます。
transform	components/transform/README.md	プロセッサー	トレース、メトリクス、ログ、プロファイル	Beta（トレース／メトリクス／ログ）、Development（プロファイル）	OTTLステートメントを適用して、スパン、メトリクスデータポイント、ログレコード、プロファイルをインプレースで変更します（属性の名前変更／マスキング／変換／集約）。OTTL言語自体についてはotel-ottlスキルを参照してください。
probabilistic_sampler	components/probabilistic_sampler/README.md	プロセッサー	トレース、ログ	Beta（トレース）、Alpha（ログ）	ヘッドサンプリングを行います。トレースID（または属性）をハッシュ化し、設定された割合のトレース／ログを決定論的に保持します。tail_samplingに対する、より低コストでステートレスな代替手段です。
attributes	components/attributes/README.md	プロセッサー	トレース、メトリクス、ログ	Beta	順序付きアクションリスト（挿入／更新／アップサート／削除／ハッシュ化／抽出／変換）を使用して、スパン／ログ／データポイントの属性を変更します。変更対象はinclude／excludeの照合条件で範囲指定します。
resource	components/resource/README.md	プロセッサー	トレース、メトリクス、ログ、プロファイル	Beta（トレース／メトリクス／ログ）、Development（プロファイル）	attributesと同じアクション構文を使用してテレメトリのリソース属性を変更します（例：service.nameの設定、不要なリソースキーの削除）。include／excludeによる照合はありません。
k8s_attributes	components/k8s_attributes/README.md	プロセッサー	トレース、メトリクス、ログ、プロファイル	Stable（トレース／メトリクス／ログ、v0.161以降）、Development（プロファイル）	各レコードをIPまたはリソース属性でポッドに関連付け、Kubernetesのポッド／名前空間／ノード／ワークロードのメタデータでテレメトリを拡充します。v0.161では、v1 semconvのゲートがデフォルトで有効になりました（単数形のk8s.pod.label.*、container.image.tags）。
routing	components/routing/README.md	コネクター	トレース、メトリクス、ログ	Alpha	コンテキストごとのOTTLcondition／statementに基づき、同じシグナルのテレメトリを異なるパイプラインにルーティングします。順序付きテーブルを使用し、最初に一致した条件が適用されます。一致しない場合はdefault_pipelinesにフォールバックします。非推奨のroutingprocessorを置き換えます。
memory_limiter	components/memory_limiter/README.md	プロセッサー	トレース、メトリクス、ログ、プロファイル	Beta（トレース／メトリクス／ログ）、Alpha（プロファイル）	OOMを防ぐ安全弁です。Goヒープがソフト／ハード制限を超えると、バックプレッシャーをかけてデータを拒否します。レシーバーミドルウェアの拡張機能はv0.158でBetaになりましたが、標準ディストリビューションには含まれていません。同梱のプロセッサーが引き続き標準形式です。
load_balancing	components/load_balancing/README.md	エクスポーター	トレース、ログ、メトリクス	Beta（トレース／ログ）、Alpha（メトリクス）	トレースID／service.name／（v0.162以降）OTelのランダム性などをキーとするコンシステントハッシュリングを介して、テレメトリを下流のCollectorに分散し、関連レコードを同じバックエンドに固定します。tail_sampling／span_metricsをスケーリングする標準的な方法です。v0.153.0でloadbalancingから名称変更されましたが、エイリアスは維持されています。
otlp（レシーバー）	components/otlp/README.md	レシーバー	トレース、メトリクス、ログ、プロファイル	Stable（トレース／メトリクス／ログ）、Alpha（プロファイル）	gRPC（4317）および／またはHTTP（4318、protobuf＋JSON）による標準的なOTLPの受信口です。protocols:ブロックは必須で、少なくとも1つのプロトコルを指定する必要があります。デフォルトのエンドポイントは0.0.0.0ではなくlocalhostです。コンテナ化されたトラフィックを受信するには、明示的に設定する必要があります。
otlp_grpc（エクスポーター）	components/otlp_exporter/README.md	エクスポーター	トレース、メトリクス、ログ、プロファイル	Stable（トレース／メトリクス／ログ）、Alpha（プロファイル）	OTLPをgRPCで下流エンドポイントに送信します。gzip、送信キュー、再試行はデフォルトで有効です。エクスポーター側の sending_queue.batchは、pkg.exporterhelper.queueBatchEnabledゲートが有効でない限り、オプトインです。core v1.50.0でotlpから名称変更されましたが、エイリアスは維持されています。
file_log（レシーバー）	components/file_log/README.md	レシーバー	ログ	Beta	ログファイル（glob include）を追跡し、各行／エントリーをログレコードに変換して、stanzaのoperatorsパイプラインで解析します。ローテーションをまたいでフィンガープリントとオフセットを追跡します。オフセットを永続化するにはstorageを使用します。v0.160では、オプトインのskip_unmodified_filesが追加されました。
resource_detection	components/resource_detection/README.md	プロセッサー	トレース、メトリクス、ログ、プロファイル	Beta（トレース／メトリクス／ログ）、Development（プロファイル）	順序付きのdetectorsリストとグローバルな再試行設定を使用して、リソース属性を自動検出します。Azure Container Apps、Azure App Service（v0.160以降）、Azure Functions（v0.162以降）の検出器が含まれます。v0.153.0でresourcedetectionから名称変更されましたが、エイリアスは維持されています。
file_storage	components/file_storage/README.md	拡張機能	—（パイプライン単位ではありません）	Beta	コンポーネントの状態をローカルディスク（bbolt）に永続化し、Collectorの再起動後も維持します。対象にはレシーバーの読み取りオフセット（storage:）、エクスポーターの永続送信キュー（sending_queue.storage:）、ステートフルプロセッサーの判定キャッシュが含まれます。コンシューマーごとにbboltファイルが1つ作成されます。create_directory: trueでない限り、directoryは事前に存在している必要があります。パイプラインには配置せず、service.extensions:に記載し、他のコンポーネントから参照します。
prometheus（レシーバー）	components/prometheus/README.md	レシーバー	メトリクス	Beta	Prometheus形式のHTTPエンドポイントをスクレイプし、OTLPメトリクスに変換します。prometheus/prometheusのスクレイプマネージャーを組み込んでいます。config:ブロックはprometheus.ymlと同じYAMLです（global、scrape_configs、scrape_config_files、サービスディスカバリー、再ラベリング）。追加キーはtrim_metric_suffixes、target_allocator（OTel Operatorからのシャーディングされたターゲット）、api_server（デバッグAPI）です。スクレイプ専用のため、remote_write／remote_read／rule_files／アラート設定は拒否します。ステートフルで、レプリカ間の自動シャーディングには対応していません。
prometheus（エクスポーター）	components/prometheus_exporter/README.md	エクスポーター	メトリクス	Beta	Prometheusがスクレイプできるよう、パイプラインのメトリクスを公開します。インメモリアキュムレーターは、古くなった系列を5m後に期限切れにします。v0.160ではresource_constant_labelsが追加され、resource_to_telemetry_conversionは非推奨になりました。add_metric_suffixesも非推奨のままで、translation_strategyへの移行が推奨されます。
prometheus_remote_write（エクスポーター）	components/prometheus_remote_write/README.md	エクスポーター	メトリクス	Beta	OTLPメトリクスをPrometheus Remote Writeとしてプッシュします。HTTPクライアント設定はhttpの下にネストし、sending_queueではなくremote_write_queueを使用します。v0.160ではresource_constant_labelsが追加され、resource_to_telemetry_conversionは非推奨になりました。RW2は引き続きゲートで制御され、開発中です。

コレクター全体の規約

名前付きインスタンス

すべてのコンポーネントタイプは type/name パターンに対応しているため、同じタイプを複数回設定できます。パイプラインでは名前付きの形式を参照します。

processors:
  log_dedup/health-checks:
    interval: 30s
    conditions:
      - 'log.attributes["log.type"] == "health_check"'
  log_dedup/access-logs:
    interval: 10s

service:
  pipelines:
    logs/health:
      processors: [log_dedup/health-checks]
    logs/access:
      processors: [log_dedup/access-logs]

安定性レベル

コンポーネントはシグナルごとに安定性レベルを公開します。本番環境での使用を推奨する際は、これらを重要な判断材料として扱ってください。

レベル	用途
Development	テストとプロトタイプのみ — 破壊的変更が想定されます。
Alpha	限定的かつ重要度の低いワークロード — 設定キーが変更される可能性があります。
Beta	本番環境で使用可能 — 破壊的変更はまれです。
Stable	本番環境 — 後方互換性が保証されます。

安定性はコンポーネントごとに異なり、複数のシグナルに対応するコンポーネントではシグナルごとにも異なります（例：redaction はトレースでは Beta、ログ／メトリクスでは Alpha です）。インデックスにあるコンポーネント全体で単一のレベルが適用されると思い込まないでください。各コンポーネントの README のヘッダーにあるメタデータ表で、正式な安定性を確認し、ユーザーから本番環境への対応状況を尋ねられた場合は、その情報を伝えてください。

最近の名称変更

v0.146.0 以降、多くのコンポーネントが snake_case に名称変更されており、変更は現在も続いています（例：v0.162.0 で awss3 レシーバーが aws_s3 に、v0.163.0 で sqlserver が sql_server に変更されています。同じファミリーのレシーバーとエクスポーターは個別に名称変更されるため、コンポーネントの metadata.yaml の type を確認してください）。以前の名称は非推奨のエイリアスとして残っており、古い設定も引き続き動作しますが、新しい設定では新しい名称を使用してください。設定が壊れていると判断する前に、上流のコンポーネント README で正確な名称変更バージョンを確認してください。

例：logdedup → log_dedup、hostmetrics → host_metrics、spanmetrics → span_metrics、servicegraph → service_graph、k8sattributes → k8s_attributes、さらに複数の _log および _check レシーバーがあります。

パイプライン内の配置

さまざまなコンポーネントに共通する目安は次の2つです。

• memory_limiter は、log_dedup、transform、tail_sampling など、バッファーを割り当てるものより前に、すべてのプロセッサーリストの先頭に配置してください。
• otlp_grpc エクスポーターの送信キューはデフォルトで有効ですが、その sending_queue.batch サブブロックはオプトインです。エクスポーター側のバッチ処理を明示的に有効にするか、アルファ版の pkg.exporterhelper.queueBatchEnabled 移行ゲートを使用してください。別個の batch プロセッサーは引き続き Beta でサポートされています。パイプラインレベルでのバッチ処理が必要な場合はこれを使用し、データを破棄するプロセッサーの後に配置してください。

検証ハーネス

各コンポーネントページの Verification セクションには、設定、telemetrygen コマンド、期待される出力が記載されています。実行するには、次の手順に従ってください。

1. YAML をファイルに保存し、そのコンポーネントを含むコレクターを起動します。contrib／k8s ディストリビューションに含まれるコンポーネントの場合は、otelcol-contrib --config <file>.yaml を実行します。どのディストリビューションにも含まれないコンポーネントの場合は、まず OpenTelemetry Collector Builder (OCB) を使ってカスタムコレクターをビルドします。
2. telemetrygen でテレメトリーを送信します（otel-telemetrygen スキルを参照）。
3. debug エクスポーターの標準出力（または file エクスポーターの出力）で期待される結果を確認します。

Verification の設定は最小限の再現例です。テスト対象のコンポーネントだけに焦点を当てるため、memory_limiter などの本番環境向けの補助設定は意図的に省略されています。本番環境でそのまま使用しないでください。

このスキルに新しいコンポーネントを追加する

対象範囲を拡張する場合：

1. ディレクトリ components/<type>/ を作成します。 ファイルにはフロントマターを付けず、フロントマターを含めるのは SKILL.md だけにします。
2. 簡潔な README.md を作成します — 常に読み込まれるため、小さく保ちます：
   • ヘッダーメタデータの表 — 種類、type 名、シグナル、シグナルごとの安定性、ディストリビューション、Go モジュール、上流の README へのリンク、コンポーネント名が変更されている場合はその注記。
   • 説明 — コンポーネントの機能とその仕組みを、簡潔な段落 1〜2 つで記述します。詳しい仕組みやリファレンスは configuration.md に記載します。
   • 主なユースケース — 「使用する場合」／「使用を避ける場合」。
   • 関連コンポーネント — 相互リンク。
   • 詳細の索引 — 各項目に、詳細ファイルへのリンクと、その内容を示す短い説明をダッシュで続ける箇条書きです（例：- [Configuration](configuration.md) — 設定キー、デフォルト値、検証）。これにより、読者は質問に必要なファイルだけを読み込めます。
3. 残りの内容は、同じディレクトリ内のオンデマンド詳細ファイルに分割します：
   • configuration.md — 設定リファレンスの完全な表（キー、型、デフォルト値、検証）と、仕組みやリファレンスに関する表。
   • verification.md — ドキュメントに記載された動作を実証する telemetrygen と debug／file エクスポーターのレシピを記載し、otel-telemetrygen スキルを相互参照します。telemetrygen のすべてのフラグをそのスキルで確認してください。存在しないフラグを記載してはいけません。 telemetrygen でコンポーネントが必要とする入力を生成できない場合は、その旨を記載し、代替手段（OTTL／transform、カスタムエミッター）を示します。設定は最小限の再現例にしてください（検証ハーネスを参照）。
   • advanced.md — 名前付きインスタンス、複数パイプラインの設定、組み合わせ、特殊な設定。
   • quirks.md — 注意点、安定性に関する留意事項、メモリモデル、検証エラーから修正方法への対応表、アンチパターン、トラブルシューティング。
   • 大きなセクションは専用ファイルに分割します（例：ポリシーカタログが大きい場合は policies.md）。些細なセクションはスタブを作らず、同系統のファイルに統合します。ファイルをまたぐようになったページ内アンカーリンクは、リンク先を変更します。
4. この構成の参考実装として components/log_dedup/ と components/interval/ を使用します。
5. 上のコンポーネント索引に行を追加します（File 列は components/<type>/README.md を指すようにします）。
6. 新しいコンポーネントがユーザー向けの明確に異なるキーワードを導入する場合、このファイルのフロントマターにある説明のトリガーフレーズを更新します。