OpenTelemetry Collector設定と基本操作 - 実践的なデータパイプライン構築 ​

OpenTelemetry Collectorを導入した後、次に重要なのは適切な設定です。Collectorはテレメトリデータを受け取り、加工し、バックエンドに送信するための中核的な役割を果たします。しかし、その設定ファイルには多くの選択肢があり、どのように構成すれば良いのか、最初は戸惑うかもしれません。このセクションでは、Collectorの設定ファイル構造から基本的なパイプライン構成、そして設定の検証方法まで、実践的な知識を身につけていきます。

Collectorの設定ファイル構造 ​

Collectorの動作を制御するすべての情報は、YAMLフォーマットの設定ファイルに定義されます。このファイルはCollectorの起動時に読み込まれ、データの収集から処理、送信までの一連のパイプラインを定義します。

基本的なYAML構造 ​

OpenTelemetry Collectorの設定ファイルは、大きく5つのセクションで構成されます。

yaml
receivers:       # データソースの定義
processors:      # データ加工・変換（オプション）
exporters:       # データ送信先の定義
extensions:      # 追加機能（オプション）
service:         # コンポーネント有効化とパイプライン定義

実際の動作では、定義されたコンポーネントは単に設定ファイルに記述されるだけでなく、後述するservice セクションで明示的に参照されなければ機能しません。これにより、設定ファイル内に複数の構成を定義しておき、必要に応じて切り替えるといった運用が可能になります。

ファイル配置とコマンド実行 ​

Collectorを起動する際に、設定ファイルの場所を指定します。デフォルトではシステムディレクトリを探しますが、カスタム設定を使用する場合は以下のように実行します。

bash
otelcol --config=config.yaml

複数の設定ファイルをマージすることもでき、その場合は複数のフラグで指定できます。

bash
otelcol --config=file:/path/to/base.yaml --config=file:/path/to/custom.yaml

データパイプラインの概念 ​

Collectorの最も重要な機能は、データが一連の処理ステップを通過するパイプラインの構築です。このパイプラインの概念を理解することが、適切な設定の第一歩になります。

このパイプラインの各段階では、異なる役割を持つコンポーネントがデータを処理します。単純なセットアップでは最小限のコンポーネントのみを使用しますが、複雑な要件に対応する際は、複数のパイプラインを並行して実行することも可能です。

Receivers - データの入り口 ​

Receiversはテレメトリデータを集約システムの外部から受け取り、Collectorに取り込むためのコンポーネントです。言わば、Collectorのデータ入口の役割を担っています。

Receiverの基本特性 ​

Receiversには大きく2つの動作モードがあります。プッシュ型はアプリケーションやエージェントからデータを受け取るモードで、OTLPやJaegerが該当します。プル型はCollector側が定期的にデータを取得するモードで、Prometheusが典型的です。

Receiverは1つの設定で複数のプロトコルをサポートできます。例えば、OTLPレシーバーはgRPCとHTTPの両方をリッスンすることが可能です。これにより、異なるクライアントからデータを受け取る柔軟性が生まれます。

よく使用されるReceiverの種類 ​

OTLPレシーバーはOpenTelemetryの標準プロトコルであり、gRPCとHTTPをサポートしています。アプリケーションはこのレシーバーを通じてトレース、メトリクス、ログを送信します。デフォルトではgRPCがポート4317、HTTPがポート4318でリッスンします。

PrometheusレシーバーはPrometheus形式のメトリクスを定期的にスクレイピング（取得）します。既存のPrometheusスクレイピング設定を再利用することも可能で、Kubernetes環境での使用頻度が特に高いです。

Jaegerレシーバーは分散トレーシングシステムJaegerからトレースデータを受け取ります。複数のプロトコル形式（gRPC、Thrift binary、HTTP）をサポートしており、既存のJaeger導入との連携が容易です。

Host MetricsレシーバーはOSレベルのシステムメトリクス（CPU、メモリ、ディスク、ネットワーク）を収集します。このレシーバーを使用することで、アプリケーションメトリクスと同時にインフラメトリクスを監視できます。

設定例 ​

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

  prometheus:
    config:
      scrape_configs:
        - job_name: 'my-app'
          scrape_interval: 15s
          static_configs:
            - targets: ['localhost:8888']

この設定では、OTLPレシーバーがgRPCとHTTPの両プロトコルでリッスンし、同時にPrometheusレシーバーが定期的にメトリクスをスクレイピングします。

Processors - データの加工・変換 ​

Receiversから受け取ったデータは、そのままバックエンドに送信することもできますが、多くの場合、何らかの加工や変換が必要です。この役割を担うのがProcessorsです。

Processorの基本的な役割 ​

Processorsはデータパイプラインの中間段階に位置し、トレース、メトリクス、ログを変換します。属性の追加や削除、データのサンプリング、リソース情報の付与など、さまざまな処理を行えます。重要なのは、Processorsの実行順序は設定ファイルに記載された順序に従うということです。つまり、1番目のProcessorの出力が2番目のProcessorの入力になります。

よく使用されるProcessor ​

Batch Processorは複数のスパンやメトリクスをバッチ化し、ネットワーク効率を向上させます。ほぼすべての本番環境で使用が推奨されています。バッチサイズやタイムアウトを設定することで、レイテンシーとスループットのバランスを調整できます。

Memory Limiter ProcessorはCollectorのメモリ使用量を制限します。高スループット環境でメモリリークやメモリ枯渇を防ぐために重要です。上限値とスパイク値を設定することで、段階的にデータを制限します。

Attributes Processorはスパンやメトリクスに属性を追加、削除、または変更します。例えば、環境名やサービス名を自動的に付与する際に使用されます。

Filter Processorは条件に基づいてデータを取捨選択します。開発環境のデータは除外する、特定のサービスのトレースだけを処理するなど、きめ細かいデータフィルタリングが可能です。

Probabilistic Sampler Processorは指定された確率でトレースをサンプリングします。高容量環境でデータ量を削減しつつ、統計的な分析を継続する場合に有効です。

設定例 ​

yaml
processors:
  batch:
    send_batch_size: 1024
    timeout: 10s

  memory_limiter:
    limit_mib: 512
    spike_limit_mib: 128

  attributes/add_env:
    actions:
      - key: environment
        value: production
        action: insert

Batch ProcessorはデフォルトでSend Batch Size（バッチ送信のトリガーとなるスパン数）を512、タイムアウトを5秒に設定しています。Memory Limiterの設定値は環境に応じて調整が必要です。512 MiBはデモンストレーション環境向けの小さい値で、本番環境では物理メモリの30～50%程度を目安に設定することが推奨されています。

Exporters - バックエンドへのデータ送信 ​

Processorsで加工されたデータは、最終的にExportersを通じてバックエンドシステムに送信されます。Exportersはバックエンドと通信するためのドライバーのような役割を果たします。

Exporterの基本特性 ​

Exportersは設定ファイルで定義されているだけでは有効になりません。後述するservice セクションのパイプライン定義で明示的に参照される必要があります。これにより、複数のExporterを定義しておき、本番環境では1つだけ有効化するといった柔軟な構成が可能になります。

よく使用されるExporter ​

OTLPエクスポーターはOpenTelemetryの標準プロトコルでデータを送信します。gRPCとHTTPの両方をサポートしており、他のCollectorインスタンスや、OTLPをサポートするバックエンドシステムに送信できます。

PrometheusエクスポーターはメトリクスをPrometheus形式で公開します。Prometheusがこのエンドポイントをスクレイピングすることで、メトリクス監視を実現します。

JaegerエクスポーターはトレースをJaegerバックエンドに送信します。Jaegerのための標準的なトレース送信方法です。

File/Debug Exporterはデータをファイルやコンソールに出力します。設定検証やトラブルシューティングに非常に有用です。

設定例 ​

yaml
exporters:
  otlp:
    endpoint: monitoring-backend:4317
    tls:
      cert_file: /etc/otel/certs/cert.pem
      key_file: /etc/otel/certs/key.pem

  prometheus:
    endpoint: 0.0.0.0:8889
    namespace: otel

  debug:
    verbosity: detailed

OTLPエクスポーターの設定では、バックエンドエンドポイントとともにTLS証明書を指定しています。Prometheusエクスポーターはメトリクスを公開するエンドポイントのアドレスとポートを指定し、Debug Exporter は詳細度レベルを設定することで、コンソール出力の詳しさをコントロールできます。

service セクション - パイプライン定義 ​

これまで説明したReceiversやProcessors、Exportersは、単に設定ファイルに記述しているだけでは機能しません。これらを実際に動作させるには、service セクション でそれらを「接続」する必要があります。言わば、service セクションはCollectorの神経系であり、データがどのように流れるかを定義する重要な部分です。

service セクション の3つの役割 ​

service セクションは3つのサブセクションで構成されます。pipelinesセクションではトレース、メトリクス、ログの処理フローを定義します。extensionsセクションでは追加機能を有効化し、telemetryセクションではCollector自身の監視設定を行います。

パイプラインの定義 ​

パイプラインは以下のように定義します。

yaml
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, memory_limiter]
      exporters: [otlp]

    metrics:
      receivers: [prometheus]
      processors: [batch]
      exporters: [prometheus]

各パイプラインはreceiversリストで複数の入力ソースを指定でき、同じProcessorやExporterを複数のパイプラインで再利用することも可能です。

複数パイプライン構成 ​

1つの物理的なCollectorで、複数の異なるパイプラインを並行実行することもできます。例えば、トレースデータはJaegerに、メトリクスはPrometheusに送信するといった構成です。

yaml
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger]

    metrics:
      receivers: [otlp, prometheus]
      processors: [batch]
      exporters: [prometheus]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

このマルチパイプライン構成により、テレメトリデータの種類に応じて異なるバックエンドに送信する柔軟な構成が実現されます。

基本的な設定パターン ​

実際の運用では、幾つかの基本的な設定パターンがあります。これらのパターンを理解することで、新しい環境への応用も容易になります。

シンプルなトレーシング設定 ​

yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  otlp:
    endpoint: jaeger-backend:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

このパターンではOTLPで受け取ったトレースをバッチ処理し、Jaegerバックエンドに送信します。最小限の構成で、多くの小規模環境で有効です。

マルチバックエンド構成 ​

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

processors:
  batch:

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317

  otlp/datadog:
    endpoint: datadog-backend:4317

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger, otlp/datadog]

複数のバックエンド（例：内部用Jaeger と外部のDatadog）に同じテレメトリデータを送信する構成です。exporter_type/name という記法で複数インスタンスを作成しています。

設定の検証 ​

新しい設定を本番環境に適用する前に、設定ファイルの妥当性を確認することが重要です。Collectorにはいくつかの検証メカニズムが備わっています。

コマンドラインでの検証 ​

bash
otelcol validate --config=config.yaml

このコマンドは設定ファイルの文法エラーや参照エラーを検出します。例えば、service セクションで指定されたReceiverやExporter が実際に定義されていない場合、エラーが報告されます。

ZPagesでの動作確認 ​

Collectorが起動している状態で、ZPages拡張機能を有効にしている場合は、ブラウザで以下のアドレスにアクセスすることで、実行時の状態を確認できます。

http://localhost:55679/debug/tracez

ここではCollectorが実際に受け取ったトレースの一覧が表示され、パイプラインが正常に動作しているかを視覚的に確認できます。

ログ出力による確認 ​

Debug Exporter を使用してコンソールに詳細なデータを出力することで、データがパイプラインを通じてどのように流れているかを確認できます。特に新しい設定を試す際の診断ツールとして有用です。

OpenTelemetry Collectorの設定は、初めは複雑に見えるかもしれませんが、5つのセクションと各コンポーネントの役割を理解すれば、大多数の要件に対応できるようになります。次のステップは、アプリケーション側の計装です。Collectorが準備できたら、実際のアプリケーションコードでOTLPを通じてテレメトリデータを送信する方法を学んでいきます。