ウクライナの国旗 ウクライナの友人や同僚を支援しています。ウクライナを支援するには このページ をご覧ください。

トラブルシューティング

よくある問題の解決

バージョン  1.62 最新

Jaeger バックエンドは、それ自体が分散システムであり、さまざまなコンポーネントで構成され、多くのホストで実行される可能性があります。これらの可動部分の1つが正しく動作していない場合があり、スパンの処理または保存が原因で発生しない可能性があります。問題が発生した場合は、ここに記載されている項目を確認してください。

パイプラインの一部として OpenTelemetry Collector を使用している場合は、独自の トラブルシューティングガイド external link を確認してください。

サンプリング戦略の検証

まず最初に、使用されているサンプリング戦略を確認してください。開発目的または低トラフィックシナリオでは、すべてのトレースをサンプリングすることが役立ちます。本番環境では、より低いレートを使用する場合があります。バックエンドでスパンの受信が行われない理由を診断する際には、SDK を構成して *すべてのトレースをサンプリング* するようにしてください。通常、サンプリング戦略は環境変数で設定できます。

OpenTelemetry SDK

OpenTelemetry SDK を使用している場合、デフォルトでは parentbased_always_on サンプラーが使用されます。これは事実上 100% のサンプリング率です。これは、OTEL_TRACES_SAMPLER 環境変数を使用して変更できます（ドキュメントを参照 external link ）。

stdout エクスポーターの使用

OpenTelemetry SDK は、記録された span を stdout に出力するエクスポーターで構成できます。これにより、span が実際に記録されているかどうかを確認できます。

Jaeger SDK（非推奨）

Jaeger SDK のいずれかを使用している場合、デフォルトでは、トレースが記録される確率が 1/1000 の確率的サンプリング戦略が使用されます。この戦略は、これらの環境変数を設定することで変更できます。

JAEGER_SAMPLER_TYPE=const
JAEGER_SAMPLER_PARAM=1

たとえば、Java 用の Jaeger SDK を使用する場合、戦略は通常、トレーサーを作成するときに、インストルメント化されたアプリケーションによって提供されるロギング機能を介して出力されます。

2018-12-10 16:41:25 INFO  Configuration:236 - Initialized  tracer=JaegerTracer(..., sampler=ConstSampler(decision=true,  tags={sampler.type=const, sampler.param=true}), ...)

ロギングレポーターの使用

ほとんどの Jaeger SDK は、インストルメント化されたアプリケーションによって提供されるロギング機能に報告されている span をログに記録できます。通常、これは環境変数 JAEGER_REPORTER_LOG_SPANS を true に設定することで実行できますが、使用している言語の Jaeger SDK のドキュメントを参照してください。特に Go と Node.js では、事実上の標準的なロギング機能がないため、Jaeger SDK によって定義された非常に狭い Logger インターフェースを実装するロガーを SDK に明示的に渡す必要があります。Java 用の Jaeger SDK を使用する場合、span は次のように報告されます。

2018-12-10 17:20:54 INFO  LoggingReporter:43 - Span reported:  e66dc77b8a1e813b:6b39b9c18f8ef082:a56f41e38ca449a4:1 -  getAccountFromCache

上記のログエントリには、トレースID e66dc77b8a1e813b、span ID 6b39b9c18f8ef082、および span の親ID a56f41e38ca449a4 の3つのIDが含まれています。バックエンドコンポーネントのログレベルが debug に設定されている場合、span とトレースの ID は標準出力に表示されます（下記の バックエンドコンポーネントのロギングの増加 を参照）。

ロギングレポーターは、サンプラーによって行われたサンプリングの決定に従います。つまり、span がログに記録されている場合、バックエンドにも到達するはずです。

リモートサンプリング

Jaeger バックエンドは リモートサンプリング をサポートしています。つまり、サンプリング戦略を中央で構成し、SDK で利用できるようにします。すべての Jaeger SDK は、JAEGER_SAMPLER_TYPE=remote を設定することでこれをサポートしています。一部の OpenTelemetry SDK もリモートサンプリングをサポートしていますが、拡張機能を介してサポートしている場合もあります（詳細は OpenTelemetry への移行 を参照）。

リモートサンプリングが正しく機能していないと思われる場合は、次の手順を試してください。

  1. SDK が実際にリモートサンプリングを使用するように構成されていること、正しいサンプリングサービスアドレスを指していること（API を参照）、およびそのアドレスがアプリケーションの ネットワークネームスペース からアクセスできることを確認します。
  2. Jaeger でキャプチャされたトレースのルートspanを確認します。Jaeger SDK を使用している場合、ルートspanには、使用された戦略を示すタグ sampler.type と sampler.param が含まれます。（未定 - OpenTelemetry SDK はそれを記録しますか？）
  3. サーバーがサービスに対して適切なサンプリング戦略を返していることを確認します。
    $ curl "jaeger-collector:14268/api/sampling?service=foobar"
    {"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":0.001}}

Jaeger Agent のバイパス

これは、Jaeger SDK を使用する場合にのみ適用されます。OpenTelemetry SDK を使用する場合、jaeger-agent の使用は 非推奨 です。

デフォルトでは、Jaeger SDK は localhost で実行されている jaeger-agent に UDP を介して span を送信するように構成されています。一部のネットワーク設定では UDP パケットがドロップまたはブロックされたり、サイズ制限が課せられたりする可能性があるため、Jaeger SDK は jaeger-agent をバイパスし、span を jaeger-collector に直接送信するように構成できます。Java 用の Jaeger SDK など、一部の SDK は、jaeger-collector の場所（例：http://jaeger-collector:14268/api/traces）を指定するために使用できる環境変数 JAEGER_ENDPOINT をサポートしています。使用している言語の Jaeger SDK のドキュメントを参照してください。たとえば、Java 用の Jaeger SDK で JAEGER_ENDPOINT プロパティを構成した場合、トレーサーの作成時に次のようにログに記録されます（sender=HttpSender に注意）。

2018-12-10 17:06:30 INFO  Configuration:236 - Initialized  tracer=JaegerTracer(...,  reporter=CompositeReporter(reporters=[RemoteReporter(sender=HttpSender(),  ...), ...]), ...)

注：Java 用の Jaeger SDK は、jaeger-collector への接続を確立できない場合でも失敗しません。span は収集され、内部バッファーに配置されます。最終的に、接続が確立されると jaeger-collector に到達するか、バッファーが最大サイズに達した場合にドロップされる可能性があります。

ネットワークネームスペース

Jaeger バックエンドが依然として span を受信できない場合（ログとメトリクスの確認方法については以下のセクションを参照）、問題はネットワークネームスペースの構成にある可能性が最も高いです。Jaeger バックエンドコンポーネントを Docker コンテナとして実行する場合、一般的な間違いは次のとおりです。

  • 適切なポートをコンテナの外側に公開していない。たとえば、コレクターはコンテナネットワークネームスペース内で :14268 でリスニングしている場合がありますが、そのポートは外部からアクセスできません。
  • jaeger-agent または jaeger-collector のホスト名をアプリケーションのネットワークネームスペースから表示できるようにしていない。たとえば、アプリケーションと Jaeger バックエンドの両方を Docker の別のコンテナで実行する場合、それらは同じネームスペースにある必要があるか、またはアプリケーションのコンテナに docker コマンドの --link オプションを使用して Jaeger バックエンドへのアクセス権限を与える必要があります。

バックエンドコンポーネントのロギングの増加

jaeger-agentとjaeger-collectorは、ログレベルがdebugに設定されている場合、役立つデバッグ情報を提供します。jaeger-agentが受信するすべてのUDPパケット、およびjaeger-agentがjaeger-collectorに送信するすべてのバッチがログに記録されます。jaeger-collectorも、受信するすべてのバッチと、永続ストレージに保存されるすべてのspanをログに記録します。

jaeger-agentを--log-level=debugフラグで起動した場合の期待されるログ出力です。

{"level":"debug","ts":1544458854.5367086,"caller":"processors/thrift_processor.go:113","msg":"Span(s) received by the agent","bytes-received":359}
{"level":"debug","ts":1544458854.5408711,"caller":"tchannel/reporter.go:133","msg":"Span batch submitted by the agent","span-count":3}

jaeger-collector側では、--log-level=debugフラグを指定した場合、以下のログエントリが期待されます。

{"level":"debug","ts":1544458854.5406284,"caller":"app/span_handler.go:90","msg":"Span batch processed by the collector.","ok":true}
{"level":"debug","ts":1544458854.5406587,"caller":"app/span_processor.go:105","msg":"Span written to the storage by the collector","trace-id":"e66dc77b8a1e813b","span-id":"6b39b9c18f8ef082"}
{"level":"debug","ts":1544458854.54068,"caller":"app/span_processor.go:105","msg":"Span written to the storage by the collector","trace-id":"e66dc77b8a1e813b","span-id":"d92976b6055e6779"}
{"level":"debug","ts":1544458854.5406942,"caller":"app/span_processor.go:105","msg":"Span written to the storage by the collector","trace-id":"e66dc77b8a1e813b","span-id":"a56f41e38ca449a4"}

/metricsエンドポイントを確認してください。

jaeger-collector側でロギングを増やすことが不可能な場合、または望ましくない場合、/metricsエンドポイントを使用して、特定のサービスのspanが受信されているかどうかを確認できます。/metricsエンドポイントは管理ポートから提供され、バイナリごとに異なります（デプロイメントを参照）。jaeger-collectorがjaeger-collectorというホスト名で利用可能であると仮定すると、メトリクスを取得するためのサンプルcurl呼び出しは次のようになります。

curl http://jaeger-collector:14269/metrics

特に重要なメトリクスを以下に示します。

jaeger_collector_spans_received
jaeger_collector_spans_saved_by_svc
jaeger_collector_traces_received
jaeger_collector_traces_saved_by_svc

最初の2つのメトリクスは、同じサービスに対して同様の値を持つ必要があります。同様に、2つのtracesメトリクスも同様の値を持つ必要があります。例えば、以下は期待通りに動作している設定の例です。

jaeger_collector_spans_received{debug="false",format="jaeger",svc="order"} 8
jaeger_collector_spans_saved_by_svc{debug="false",result="ok",svc="order"} 8
jaeger_collector_traces_received{debug="false",format="jaeger",svc="order"} 1
jaeger_collector_traces_saved_by_svc{debug="false",result="ok",svc="order"} 1

Istio: spanが見つかりません

Istioなどのサービスメッシュの一部としてアプリケーションをデプロイする場合、可動部分の数が大幅に増加し、spanのレポート方法（およびどのspanをレポートするか）に影響を与える可能性があります。Istioによって生成されたspanが表示されることが期待されるが、Jaeger UIに表示されない場合は、Istioのウェブサイト external link のトラブルシューティングガイド

を確認してください。

バックエンドコンポーネントのデバッグイメージを実行します。

各Jaegerコンポーネントのデバッグイメージを提供しています。これらのイメージには、delve external link と、最適化を無効にしてコンパイルされたそれぞれのJaegerコンポーネントが含まれています。これらのイメージを実行すると、delveはJaegerコンポーネントを子プロセスとして実行し、すぐにそれにアタッチして新しいデバッグセッションを開始し、リモート接続のためにTCPポート12345でリスニングを開始します。その後、Visual Studio Code external link やGoLand external link などのIDEを使用してこのポートに接続し、リモートでアタッチして、デバッグ external link を行うことができます（ブレークポイントを追加します）。

Visual Studio Codeの場合、Jaegerソースコードのローカルクローンルートに次の設定が必要です。

$ cat .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch remote",
            "type": "go",
            "request": "attach",
            "mode": "remote",
            "remotePath": "",
            "port": 12345,
            "host": "127.0.0.1",
            "cwd": "${workspaceRoot}",
        }
    ]
}