otel-collector

OpenTelemetry Collector の設定ガイド

テレメトリを受信、処理、エクスポートするための OpenTelemetry Collector の設定とデプロイに関する専門的なガイダンスです。

ルール

ルール	説明
receivers	レシーバー — OTLP、Prometheus、filelog、hostmetrics
exporters	エクスポーター — Dash0 への OTLP/gRPC、デバッグ、認証
processors	プロセッサー — メモリーリミッター、リソース検出、順序、送信キュー
pipelines	パイプライン — service セクション、シグナルごとの設定、コネクター
deployment	デプロイ — エージェントとゲートウェイのパターン、デプロイ方法の選択
dash0-operator	Dash0 Kubernetes Operator — 自動インストルメンテーション、Collector の管理、Dash0 へのエクスポート
collector-helm-chart	Collector Helm チャート — プリセット、モード、イメージの選択
opentelemetry-operator	OpenTelemetry Operator — Collector CRD、自動インストルメンテーション、サイドカー
raw-manifests	Kubernetes の生マニフェスト — DaemonSet、Deployment、RBAC、Docker Compose
sampling	サンプリング — ヘッド、テール、ロードバランシング
red-metrics	RED メトリクス — スパンから導出されるリクエストレート、エラーレート、期間ヒストグラム
custom-distributions	カスタムディストリビューション — OCB を使用した軽量化 Collector バイナリーのビルド

主な原則

• プロセッサーの順序は重要です。 すべてのパイプラインで memory_limiter を最初に配置します。 sending_queue: { batch: {} } でエクスポーターのバッチ処理を有効にし、batch プロセッサーを使う代わりに file_storage でキューを永続化します。 順序を誤ると、メモリー不足やデータ損失が発生します。
• シグナルの種類ごとにパイプラインを分けます。 トレース、メトリクス、ログごとに個別のパイプラインを定義します。 1 つのパイプラインでシグナルを混在させると、処理が破綻し、実行時エラーが発生します。
• 宣言したすべてのコンポーネントをパイプラインに含める必要があります。 Collector は、どのパイプラインからも参照されていないコンポーネントを、エラーや警告を出さずに無視するため、配線されていないコンポーネントは機能しません。
• すべてのパイプラインでリソース属性を一貫して付与します。 resource_detection や k8s_attributes などのリソース属性を付与するプロセッサーは、1 つのパイプラインだけでなく、すべてのシグナルパイプライン（トレース、メトリクス、ログ）に適用します。 あるパイプラインではテレメトリに k8s.namespace.name や host.name を付与し、別のパイプラインでは付与しない場合、メタデータが不完全になり、シグナル間の相関が損なわれます。
• 標準のコンポーネント名を使用します。 設定キーには otlp_grpc、otlp_http、load_balancing、span_metrics、log_dedup、signal_to_metrics、k8s_attributes、resource_detection を記述します。 旧名の otlp（エクスポーターのみ）、otlphttp、loadbalancing、spanmetrics、logdedup、signaltometrics、k8sattributes、resourcedetection も非推奨のエイリアスとして引き続き動作しますが、起動時に非推奨の警告が記録されます。
• Collector v0.153.0 以降を実行します。 このスキルの設定にはこのバージョンが必要です。load_balancing と resource_detection は v0.153.0 以降でのみ利用でき、sending_queue.batch: {} は v0.138.0 以降でのみ利用できます。 古い Collector は起動時にこれらを拒否します。新しい名前では unknown type、batch: {} では 'sending_queue' has invalid keys: batch または `batch` supports only `items` or `bytes` sizer が発生します。 イメージのバージョンを固定する場合は、例で使用しているバージョン v0.163.1 に固定してください。
• メモリーの安全性は必須です。 本番環境では必ず memory_limiter を設定します。 設定しないと、テレメトリの急増によって Collector が OOM になり、クラッシュする可能性があります。

クイックスタート

最小限の動作する構成：OTLP レシーバー → メモリリミッター → Dash0 への OTLP/gRPC エクスポーター。

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 400
    spike_limit_mib: 100

exporters:
  otlp_grpc:
    endpoint: ingress.eu-west-1.aws.dash0.com:4317
    headers:
      Authorization: "Bearer ${env:DASH0_TOKEN}"
    sending_queue:
      enabled: true
      storage: file_storage
      batch: {}

extensions:
  file_storage:
    directory: /var/lib/otelcol/queue
    create_directory: true

service:
  extensions: [file_storage]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp_grpc]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp_grpc]
    logs:
      receivers: [otlp]
      processors: [memory_limiter]
      exporters: [otlp_grpc]

Collector のユーザーには file_storage ディレクトリへの書き込み権限が必要です。コンテナでは、/var/lib/otelcol に永続ボリュームをマウントしてください。

認証とキューの設定についてはエクスポーターを、リソース検出の追加についてはプロセッサーを参照してください。

構成のワークフロー

1. 構成を記述する — レシーバー、プロセッサー、エクスポーターを定義し、service.pipelines で接続します。
2. ローカルで検証する — デプロイ前に otelcol validate --config=config.yaml を実行し、構造上のエラーを検出します。
3. デプロイする — デプロイルールからデプロイ方法（Helm、Operator、raw manifests、Docker Compose）を選択します。
4. 確認する — パイプラインに一時的に debug エクスポーターを追加し、標準出力を調べてテレメトリが流れていることを確認します。本番環境に移行する前に削除してください。

クイックリファレンス

必要なもの	ルール
アプリケーションから OTLP テレメトリを受信する	レシーバー
Prometheus エンドポイントをスクレイプする	レシーバー
ログファイルまたはホストメトリクスを収集する	レシーバー
テレメトリを Dash0 に送信する	エクスポーター
リトライ、キュー、圧縮を設定する	エクスポーター
プロセッサーの実行順序を設定する	プロセッサー
Kubernetes またはクラウドのメタデータを追加する	プロセッサー
レシーバー → プロセッサー → エクスポーターを接続する	パイプライン
完全な動作構成	パイプライン
デバッグエクスポーターでパイプラインを検証する	collector-helm-chart、opentelemetry-operator、raw-manifests、または dash0-operator
DaemonSet または Deployment としてデプロイする	raw-manifests
Helm でデプロイする	collector-helm-chart
OTel Operator でデプロイする	opentelemetry-operator
Dash0 Operator でデプロイする	dash0-operator
Kubernetes でアプリケーションを自動計装する	opentelemetry-operator または dash0-operator
Docker Compose でローカル開発する	raw-manifests
トレース量を減らす	サンプリング
エラーと遅いトレースを保持し、それ以外を破棄する	サンプリング
パイプライン内の機密データをマスキングする	プロセッサー
トレースから RED メトリクスを生成する	red-metrics
カスタム Collector バイナリをビルドする	カスタムディストリビューション

公式ドキュメント

• OpenTelemetry Collector のドキュメント
• Collector の構成
• Collector contrib コンポーネント
• Dash0 Integration Hub