AWS Distro for OpenTelemetry（ADOT）Collectorの設定ファイルについて調べてみた

とーち
2025.04.01
お疲れさまです。とーちです。
OpenTelemetryについて調べる機会がありました。AWS Distro for OpenTelemetry Sample Code with Go SDKを使って、実際に実装して動作を確認していたのですが、Collectorの設定を適当にやっていたので、エラーが出て詰まりました。
Collectorの設定を理解することで何が原因だったのかが明確になったので、この記事では各設定項目について解説していきたいと思います。
なお、そもそもOpenTelemetryとは何か？については以下の記事が大変分かりやすいです。ぜひご参照ください。
https://zenn.dev/ryoyoshii/books/opentelemetry-firststep/viewer/whatis
 検証環境と発生していた事象私が検証に使用していた環境は以下のようなものでした
ALB（パブリックサブネット）
Amazon ECS Fargate（プライベートサブネット）
ECSタスクのコンテナ
AWS Distro for OpenTelemetry Sample Code with Go SDKのサンプルプログラム
サイドカーコンテナとしてADOT Collector

Go言語のサンプルプログラムは問題なくECS上で稼働しており、ブラウザからのリクエストに対しても応答を返せる状態でしたが、コンテナのログを見ると以下のエラーメッセージが出ていました
rpc error: code = Unimplemented desc = unknown service opentelemetry.proto.collector.metrics.v1.MetricsService
調べてみるとOpenTelemetry のメトリクスサービスが実装されていないか、適切に設定されていないことを示しているとのこと。また一般的な解決策としてはCollectorの設定を修正する必要があるとのことでした。
こちらは原因としては、ADOT Collectorの設定ファイルのservice項目に metrics がないことが原因でしたので、今回はこちらのファイルを使って対応したのですが、設定ファイルの意味がわかっていればもっと早く解決できたと思います。
今回使用していたCollectorのコンテナイメージは、AWS公式のADOT Collectorイメージです
https://gallery.ecr.aws/aws-observability/aws-otel-collector
このイメージには、いくつかのプリセット設定ファイルが用意されています。そのため、カスタムイメージをビルドせずに、パブリックに公開されているイメージにコマンドで --config=/etc/ecs/ecs-default-config.yaml と指定するだけで、ある程度トレースを取れるようになっています。（そのため、設定ファイルの意味をちゃんと理解せずになんとなく使ってしまっていました・・・）
詳しくは以下のドキュメントをご覧ください
https://aws-otel.github.io/docs/setup/ecs/task-definition-for-ecs-fargate
 ADOT Collectorの設定ファイルを理解するそれでは、ADOT Collectorの設定ファイルの意味をちゃんと読み解いていきましょう。今回は以下のファイルを元に各設定値の意味を調べました
https://github.com/aws-observability/aws-otel-collector/blob/main/config/ecs/ecs-xray.yaml
なお、OpenTelemetryの公式ドキュメントは以下をご参照ください
https://opentelemetry.io/docs/collector/configuration/
 ECSでOpenTelemetryを使う場合の構成要素ECSでOpenTelemetryを使う場合の構成要素を把握しておくと、後の説明がより理解しやすくなると思います。OpenTelemetryの構成要素としては大きく以下の3つがあります
OpenTelemetry SDK：ユーザーが作成したプログラムに実装されるOpenTelemetry用のSDKです。Go言語だと go get go.opentelemetry.io/otel といった形で外部パッケージとしてインストールします。SDKがプログラムの中で発生したトレースやメトリックなどをCollectorに送信します。
OpenTelemetry Collector：OpenTelemetry SDKを含むユーザープログラムから情報を受け取るのがCollectorで、Amazon ECS Fargateなどではサイドカーコンテナとして実装されます。Collectorがトレースやメトリック情報をバッファしたり、どのObservability Backendに送信するかを決定します。
Observability Backend：AWS X-RayやDatadog、New Relicなど、データを収集し閲覧分析するための最終的な送信先がObservability Backendです。
（画像出典：One Observability Workshop）
 Collectorの設定ファイルの概要Collectorの設定ファイルの全体的な構成は以下のようになっています。extensions〜exportersまでで各要素を定義し、serviceで各要素をどう組み合わせるかを定義する構成となっています。
extensions：コレクタの拡張機能を定義します。
receivers：ユーザーが作成したアプリケーションからトレースやメトリックを受け取るのがレシーバーです。この項目ではレシーバーのポート番号やプロトコルなどを定義します。
processors：レシーバーが収集したデータをObservability Backendに送る前に変換やバッファリングなど中間処理をすることが可能です。プロセッサはこの中間処理を定義します。
exporters：ここでは最終的な送信先であるObservability Backendを定義します。
service：上記の要素を組み合わせて、どのレシーバーで受け取ったデータをどのプロセッサで処理し、最終的にどのエクスポーターに送るかを記述するのがservice定義です。
それでは各要素を細かく見ていきましょう。
 1. ヘルスチェック拡張機能extensions:
  health_check:
    # ヘルスチェックエンドポイントを有効化
extensionsは拡張機能を定義する項目です。決められた拡張機能の名前を記述することでその拡張機能が有効になります。ヘルスチェック要求に応答するヘルスチェック拡張機能や、コレクタのパフォーマンス情報を取得できるPProf拡張機能などがあります。
 2. レシーバーの設定receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317  # gRPCプロトコルでのリッスンアドレスとポート
      http:
        endpoint: 0.0.0.0:4318  # HTTPプロトコルでのリッスンアドレスとポート
receiversに必要なレシーバーを定義します。複数のレシーバーを定義できます。
otlpなどデフォルトで用意されているレシーバーがあり、こういったものはデフォルトの設定が存在するので、以下のように少ない記述で使用することができます
receivers:
  otlp:
    protocols:
      grpc:
      http:
ドキュメントを見ると、他にも fluentforward などFluent系から情報を受け取るためのレシーバー設定もあるようですね。
なお、otlpはOpenTelemetryの標準レシーバーで、トレース、メトリック、ログの全てのデータタイプを受信できます。
ここでは、gRPCとHTTPの両方のプロトコルで、それぞれ4317ポートと4318ポートでリッスンするよう設定しています。
otlpの設定項目としては endpoint という設定があり、ここではレシーバーがデータを受信する ホスト:ポート番号 を指定します。
otlpの他の設定については以下のページに記載があるのでご参照ください
opentelemetry-collector/receiver/otlpreceiver at main · open-telemetry/opentelemetry-collector · GitHub
 3. プロセッサーの設定processors:
  batch/traces:
    timeout: 1s            # バッチ処理のタイムアウト時間
    send_batch_size: 50    # 一度に送信するトレース数
  resourcedetection:
    detectors: [env, system, ecs, ec2]  # 使用するリソース検出器
プロセッサにはObservability Backendに送る前の中間処理を複数定義できます。ここでは以下の2つのプロセッサを定義しています
batch/traces:
バッチプロセッサーは、個々のテレメトリデータ（トレースやメトリック）を一定期間または一定量蓄積し、まとめて送信するためのプロセッサです。
timeout は最後のテレメトリデータを受信してから指定した時間が経過すると、データが送信されることを意味します。
send_batch_size は一度に送信するバッチのサイズを50個に設定し、50個のトレースデータが蓄積されると、タイムアウトを待たずに即座にバッチが送信されます。
ご参考
resourcedetection:
環境変数、システム情報、ECS、EC2などからリソース情報を自動検出し、テレメトリデータ内の値を追加または上書きできます。
リソース検出器を detectors に羅列することでその検出器を使用してデータの検出がされます。
env が環境変数、system がホストのアーキテクチャやIPアドレスなどを検出できます。ecs、ec2 はその名の通りテレメトリデータ送信元のECSやEC2から情報を取得できます。
ご参考
 4. エクスポーターの設定exporters:
  awsxray:
    # AWS X-Rayへのエクスポート設定
ここでは、AWS X-Rayを最終的なデータ送信先として定義しています。この他に、prometheus や datadog/exporter などが定義できます。
 5. サービスパイプラインの定義service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch/traces]
      exporters: [awsxray]
  extensions: [health_check]
最後に、serviceの定義です。
pipelinesで上記で定義した各要素をどのように組み合わせるかを定義します。
上記の例だと、
otlp レシーバーからデータを受け取る
受信したトレースデータに対して2つのプロセッサー（resourcedetection, batch/traces）を順番に適用
処理されたトレースデータを awsxray エクスポーターに送信
という処理の流れとなります。
また、パイプラインはテレメトリデータのタイプごとに異なる処理パイプラインを定義する形となっています。
上記ではトレースデータのパイプラインのみ定義されていますが、メトリックデータも送るという場合は metrics という文字列でメトリック用のパイプラインを定義する形です。
また、extensionsについては、設定ファイル冒頭の extensions で定義してかつ、このserviceで extensions: [health_check] という形で有効にする必要がある点に注意です。
 まとめ今回は、ADOT Collectorの設定ファイルの各項目について詳しく解説しました。
この記事が、OpenTelemetryを使った監視設定の理解の助けになれば幸いです。
以上、とーちでした。