OpenTelemetryセットアップのトラブルシューティング ​

OpenTelemetryを導入して、テレメトリデータを送信するまでの過程では、いろいろな問題が発生することがあります。データが受信されない、パフォーマンスが低下するなど、原因の特定が難しい場合も多いです。このガイドでは、実際に遭遇しやすい問題と、体系的なトラブルシューティング手順を紹介します。効率的にデバッグして、安定したObservability基盤を構築しましょう。

セットアップ時の一般的な問題カテゴリ ​

OpenTelemetryのセットアップでは、大きく3つの問題パターンに分けられます。

データ受信の問題 - Collectorがデータを受信できない、または処理中に失われるケース。Collectorが正しく起動していても、データが到着していないことが多いです。

制御・実行の問題 - Collectorが予期せず終了したり、起動時にエラーが発生したりするケース。メモリ不足やリソース制限が原因になることが一般的です。

設定の問題 - 設定ファイルの記述誤りや、意図しないオーバーライドによって動作がおかしくなるケース。Collectorのパイプライン設定では後続の設定が前の設定を上書きします。

データが送信されない時の診断フロー ​

データが送信されない場合、以下のフローに沿って問題を絞り込んでいきます。

このフローで重要なのは、問題がどこで発生しているかを特定することです。アプリケーション側なのか、Collector側なのか、ネットワーク側なのかが明確になれば、対応も限定されます。

ステップ1: Collectorのログを確認する ​

Collectorが正常に起動し、データを処理しているかは、ログを見ることで最初に判断できます。Collector起動時に、以下のようなログが出力されていることを確認してください。

Collector started.

このメッセージが出ていない場合は、起動時にエラーが発生しています。起動ログを詳しく確認して、エラーメッセージから原因を特定します。よくある起動エラーは、設定ファイルの記述誤りやバインドエラー（ポート既使用など）です。

Collectorが起動している場合、受信・処理・エクスポートの各段階でログが出力されます。特に確認すべきポイントは、データ受信時のログです。設定したreceiverが正しくデータを受信していれば、対応するログが表示されます。

設定ファイルに誤りがあると、「Null maps」という警告が出ることがあります。これは、設定ファイルの後続部分が前の設定を意図せず上書きしてしまう場合に発生します。設定の記述順序と依存関係を確認してください。

ステップ2: ローカルエクスポーターでテストする ​

Collector側で実際にデータが処理されているかを確認するには、stdoutまたはdebugエクスポーターを使用して、ローカルにデータをダンプするのが最も直接的です。

Collector設定で、loggingまたはdebugエクスポーターを一時的に追加します。標準出力にテレメトリデータがJSON形式で表示されれば、データは正常に処理されています。これは、バックエンド側の設定が原因で、外部へ送信できていない場合の診断に有効です。

ローカルエクスポーターの追加は、本番環境では外してください。大量のデータが出力されるため、パフォーマンスに大きく影響します。

ステップ3: zPages拡張で内部状態を確認する ​

Collector内部の状態をリアルタイムで確認するには、zPages拡張が便利です。CollectorにzPages拡張を含めて起動すると、ブラウザからアクセスできるダッシュボードが提供されます。

デフォルトではポート55679で動作します。http://localhost:55679/debug/tracez にアクセスすると、Collectorが処理しているトレースの詳細情報が表示されます。特に、以下の情報が確認できます。

Received spans - Collectorが受け取ったスパンの数と詳細。データがreceiverに到達しているかどうかがわかります。

Exported spans - Collectorがバックエンドにエクスポートしたスパンの数。エクスポートが成功しているかどうかの確認ができます。

Latency - 各スパンの処理にかかった時間。パフォーマンスのボトルネック検出に有用です。

zPagesを使用する場合、Collector設定の拡張セクションでzpagesを有効化する必要があります。

パフォーマンス問題への対応 ​

Collectorがデータを処理する際に大きな遅延が発生していないか、CPU使用率やメモリ使用量が異常に高くないか確認してください。

データの損失が発生している場合 - Collectorのmemory_limiterプロセッサ設定を確認します。このプロセッサは、メモリ使用量が設定された閾値を超えた際に、新しいデータを破棄してCollectorの異常終了を防ぎます。継続的にメモリリミッターに達する場合は、Collectorのリソース割り当てを増やすか、パイプライン設定を見直して処理を効率化します。

遅いエクスポーターが原因の場合 - バックエンド接続がネットワークの遅延や帯域幅制限の影響を受けていないか確認します。バッチサイズやタイムアウト設定を調整することで改善することもあります。

受信側の問題の場合 - アプリケーションからの送信が遅い、またはバースト的に大量に送信されていないか確認します。スパン生成のレートを把握することで、Collector側のリソース要件も決めやすくなります。

ネットワークとファイアウォール問題 ​

データが送信されない最も一般的な理由が、ネットワークレベルの問題です。Collectorがリッスンしているポートが、クライアント（アプリケーション）から正しくアクセスできているかが重要です。

ファイアウォールの確認 - アプリケーションが動作しているマシン、またはネットワークセグメントからCollectorへのアクセスがブロックされていないか確認します。特にクラウド環境では、セキュリティグループやネットワークACLの設定が影響します。

接続テスト - telnet <collector-host> <port> や nc -zv <collector-host> <port> で接続可能か簡易テストできます。接続タイムアウトが発生する場合は、ホスト名またはポート番号が誤っている、またはファイアウォールでブロックされている可能性があります。

DNS解決の確認 - Collector接続時にホスト名を使用している場合、DNS解決が正常に行われているか確認します。nslookup または dig コマンドでホスト名が正しく解決されているか調べます。

プロキシ設定 - 企業ネットワークではHTTPプロキシを経由する場合があります。Collectorおよびクライアント側でプロキシ設定が正しく行われているか確認してください。Collectorは環境変数または設定ファイルでプロキシをサポートします。

よくあるエラーとその対応 ​

設定や実行時に出くわすエラーメッセージと、その対応方法を紹介します。

トラブルシューティング時の実用的なチェックリスト ​

問題が発生した時の診断順序をまとめました。このチェックリストに沿って、段階的に問題を絞り込んでいきます。

サポートリソースと相談窓口 ​

問題が解決しない場合は、以下のリソースが役立ちます。

公式ドキュメント - OpenTelemetryの公式Webサイトには、詳細なトラブルシューティングガイドと設定例が掲載されています。言語別やコンポーネント別に、わかりやすくまとめられています。

コミュニティSlack - OpenTelemetryコミュニティは活発で、専用のSlackチャネルで質問できます。多くの経験者が即座にアドバイスしてくれる場合があります。

GitHubイシュー - 特定のコンポーネント（言語SDKやCollectorなど）での既知の問題や、同じ問題を経験した他のユーザーのレポートが見つかる可能性があります。

StackOverflow - タグ「open-telemetry」で検索すると、多数のQ&A記事が出ます。同じ問題の解決例が見つかることも多いです。

セットアップの過程で遭遇する問題は、正確な診断と段階的なテストによってほぼすべて解決できます。このガイドに沿ってアプローチすれば、効率的にトラブルシューティングを進めることができます。次のステップでは、バックエンドサービスとの連携設定について学んでいきましょう。