Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

第5章 運用と設計のベストプラクティス

本章では、OpenTelemetry を実際のプロダクション環境で安定運用するためのベストプラクティス（コンテキスト伝播、サンプリング戦略、機密情報の保護、トラブルシューティング）を解説します。

分散トレーシングとコンテキスト伝播（Context Propagation）

複数のサービスがネットワークを介して連携する場合、トレース情報を後続のサービスへ引き継ぐ必要があります。この仕組みを「コンテキスト伝播」と呼びます。

OpenTelemetry では、W3C が標準化した W3C Trace Context 仕様を採用しています。HTTP リクエストを送信する際、ヘッダーに以下の情報が付加されます。

  • traceparent: トレース全体の識別子（Trace ID）と現在のスパン識別子（Span ID）、サンプリングフラグを結合した文字列。
  • tracestate: ベンダー固有の追加情報を運ぶキーバリューストア。

HTTP クライアントライブラリ（Python の requests や C# の HttpClient）に対して自動インストルメンテーション（または手動でのヘッダーインジェクション）を適用することで、開発者が意識することなくサービス間で同一の Trace ID が共有されます。

サンプリング戦略（Sampling Strategy）

本番環境で大規模なトラフィックが発生する場合、すべてのリクエスト（100%）をトレースすると、ネットワーク帯域やストレージ費用を圧迫します。そのため、目的に応じたサンプリングが必要です。

  • Head-based サンプリング（リクエスト開始時に判定）

    リクエストが開始された瞬間に、SDK 側で「このトレースを記録するかどうか」を決定します（例: 全体の 5% のみを均等にサンプリング）。シンプルで軽量ですが、エラーが発生した重要なリクエストがサンプリングから漏れてしまう可能性があります。

  • Tail-based サンプリング（リクエスト完了時に判定）

    OpenTelemetry Collector 内の tail_sampling プロセッサーを使用して実現します。Collector 側でトレース全体が完了するまで一時的にバッファリングし、「HTTP ステータスが 500 番台のエラー」「処理時間が 2 秒を超えた遅延リクエスト」のみを 100% 保存し、正常なリクエストは 1% のみ保存するといった高度な制御が可能です。

セマンティック規約と機密情報の保護

テレメトリデータに付加する属性（Attributes）には、OpenTelemetry が定めた「セマンティック規約（Semantic Conventions）」に従った命名を使用します。

  • HTTP 通信: http.request.method, http.response.status_code, url.path
  • データベース: db.system, db.name, db.statement

これにより、異なるプログラミング言語やライブラリで作成されたサービス間でも、統一されたキーでダッシュボードやアラートを作成できます。

また、テレメトリデータにパスワード、クレジットカード番号、個人名（PII: Personally Identifiable Information）が混入しないよう徹底する必要があります。OpenTelemetry Collector の transform プロセッサーなどを利用し、送信前に機密属性をハッシュ化またはマスクする防御策を設けることが推奨されます。

トラブルシューティング

テレメトリデータが Jaeger や Prometheus に届かない場合は、以下の順序で原因を切り分けます。

  1. Collector のログを確認する

    Collector の設定ファイルで debug エクスポーターを有効にしておくと、受信したスパンやメトリクスの件数がコンテナログに出力されます。データが Collector まで届いているかを確認します。

    docker compose logs -f otel-collector

  2. ポートと通信プロトコルの一致を確認する

    クライアントコードが指定しているポート番号（gRPC: 4317、HTTP: 4318）が、Docker Compose で正しくホストへマッピングされているか確認します。

  3. SDK のフラッシュとシャットダウン

    コンソールアプリやバッチ処理などの短期実行スクリプトでは、provider.shutdown() または provider.force_flush() を呼ばずにプログラムが終了すると、バッファ内のデータが送信されずに破棄されます。プログラム終了時に確実にシャットダウンが行われているか確認します。