OpenTelemetry OpenTelemetry

OpenTelemetry を解説する：SDK、OTLP、Collector

YAML を 1 行も書く前に、構成要素と、設定が存在する 3 つの場所を理解します。

8 min learn.level.初級

OpenTelemetry には多くの部品があり、混乱の大半は、それらを混同することから生じます。このガイドでは、それらを分けて説明します。アプリケーションの内部で動作するもの、その隣で動作するもの、それぞれがどこで設定されるかです。全体像が明確になれば、このシリーズの残りは、主に YAML を埋めていく作業になります。

解決する問題

OpenTelemetry 以前は、監視ベンダーごとに独自のエージェントと独自のデータ形式がありました。ベンダーを切り替えるには、すべてのサービスを再計装する必要があり、2 つのツールを動かすことは、2 つのエージェントを動かすことを意味しました。OpenTelemetry は、2 つの関心事を分離します。計装は標準のデータを 1 度だけ生成し、パイプラインがそれをどこに送るかを決めます。

構成要素

構成要素内容動作する場所
API計装のコードが呼び出すインターフェース（スパンの開始、メトリクスの記録）アプリ内
SDKAPI の背後にある実装：サンプリング、バッチ処理、エクスポートアプリ内
計装ライブラリ（HTTP、データベース）向けのテレメトリを作成するコードアプリ内。ライブラリまたはコード不要のエージェント経由
OTLPgRPC または HTTP でのテレメトリのワイヤープロトコルコンポーネント間
Collectorテレメトリを受信、処理、エクスポートする、スタンドアロンのサービスアプリの隣、ノードごと、または中央のゲートウェイとして
セマンティック規約http.request.method のような属性の標準的な名前あらゆる場所

アプリケーションは、バックエンドに直接エクスポートできますが、間に Collector を置くのが通常の推奨です。アプリケーションを再デプロイせずに、処理と宛先を変更できるからです。

設定の 3 つの層

  1. アプリケーションの SDK。OTEL_* 環境変数、または、ますます多く、OTEL_CONFIG_FILE が指す宣言的な YAML ファイルで設定されます。サービス名、リソース属性、サンプラー、エクスポート先を制御します。
  2. Collector。YAML ファイルで設定されます。何を受信するか、データをどう変換するか、どこに送るかを制御します。
  3. プラットフォームの接着剤：Docker Compose のファイル、Helm の values、OpenTelemetry Operator の Kubernetes リソースで、Collector をデプロイし、アプリケーションに設定を注入します。

これらの層のすべてがテキストなので、Git に置けます。

データフローを 1 枚の図で

┌────────────┐  OTLP   ┌─────────────────────────────┐        ┌───────────┐
│ App + SDK  │────────▶│ Collector                   │───────▶│ トレース   │
│ (環境変数    │ 4317/   │ receivers → processors →    │───────▶│ メトリクス │
│  または YAML)│ 4318    │ exporters (config.yaml)     │───────▶│ ログ      │
└────────────┘         └─────────────────────────────┘        └───────────┘

シグナルの概要

  • トレースは、サービスを通るリクエストの経路を、スパンとして記録します。「時間はどこで使われたか」に答えます。
  • メトリクスは、リクエスト数やレイテンシーのヒストグラムのように、時間にわたる数値の測定値です。「システムの傾向はどうか」に答えます。
  • ログは、タイムスタンプ付きのレコードです。OpenTelemetry はそれをトレースと相関させられるため、ログ行は、それを生成したスパンにリンクします。

各シグナルには、Collector に独自のパイプラインがあり、SDK に独自のプロバイダーがあります。

安定性：導入する前に読む

OpenTelemetry は大規模で、その部分ごとに成熟の速度が異なります。OTLP プロトコルと、トレースとメトリクスの API は安定しています。Collector のコンポーネントはそれぞれ独自の安定性レベルを持ち、contrib のコンポーネントの多くは、まだ beta や alpha です。宣言的な SDK 設定は、2026 年にスキーマが安定版に達しましたが、SDK の実装の追従には差があり、Java やいくつかの他の言語が先行しています。コンポーネントや機能を選ぶときは、ドキュメントで安定性を確認し、バージョンを固定してください。

このシリーズでの推奨の進め方

  1. Collector を実行して、データを送ります（Docker Compose）。
  2. Collector の設定モデルを学びます。
  3. 環境変数と、サポートされている場合は宣言的なファイルで、SDK を設定します。
  4. アプリケーションにコード不要の計装を追加します。
  5. Collector を本番向けにします：バッチ処理、メモリ制限、リトライ、サンプリング。
  6. Helm または Operator で Kubernetes にデプロイします。
  7. ログとインフラのメトリクスを収集し、バックエンドに安全に送り、トラブルシューティングします。

リファレンスとしては、OpenTelemetry のドキュメントを参照してください。

人気のガイド