トラブルシューティング

このページには、Trace のトラブルシューティング情報が記載されています。

既知の問題

このセクションでは、既知の問題について説明します。

  • Telemetry API を使用して Google Cloud プロジェクトに書き込まれたスパンは、Cloud Trace API からアクセスできません。たとえば、これらのトレースを一覧表示しようとすると、コマンドは 404 Not Found エラーで失敗します。

ログ分析のトラブルシューティング

このセクションでは、ログ分析を使用してトレースデータをクエリするときに発生する可能性のあるエラーを解決する方法について説明します。

ビューが存在しないことを示すエラー メッセージ

[ログ分析] ページのクエリペインに SQL クエリを入力しますが、SQL パーサーは次のエラーを表示します。

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views/OBS_VIEW_ID does not exist

上記のエラーは、FROM ステートメントで指定されたビューが見つからない場合に報告されます。

このエラーを解決するには、ビューの構文が正しいことを確認します。

  • ビューの完全修飾名が、ログ分析の命名規則で必要な構文に従っていることを確認します。ビューに必要な構文は、デフォルトのクエリを表示することで確認できます。

  • Google Cloud プロジェクト ID、ロケーション、バケット ID、データセット ID、またはビュー ID にピリオド（(.)）が含まれている場合は、フィールドが単一バッククォート（(`)）で囲まれていることを確認します。

    たとえば、 Google Cloud プロジェクトの ID が example.com:bluebird の場合、FROM ステートメントは次のようになります。

    FROM `example.com:bluebird`.`us`.`_Trace`.`Spans`.`_AllSpans`

[Trace エクスプローラ] ページにデータがない

Google Cloud プロジェクトにトレースデータを送信するアプリケーションがある。ただし、[Trace エクスプローラ] ページを開いてもデータは表示されません。

トレースデータを表示できない理由としては、次のようなものが考えられます。

  • データを表示するために必要な権限が付与されていません。
  • トレース スパンがプロジェクトに送信されませんでした。
  • トレースデータを書き込むために必要な権限がアプリケーションにありません。
  • トレース スパンが保存されていません。

次のサブセクションでは、リストに記載されている障害シナリオのトラブルシューティング方法について説明します。

トレースデータを表示する権限があることを確認する

トレースデータを表示するには、Cloud Trace ユーザーロール（roles/cloudtrace.user）が付与されていることを確認してください。

トレース スパンがプロジェクトに送信されていることを確認する

スパンがプロジェクトに送信されていることを確認する手順は次のとおりです。

  1. Enable the Cloud Trace and Telemetry APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    どちらの API もトレース スパンを取り込むことができます。ただし、Telemetry API は OpenTelemetry エコシステムと互換性があり、Cloud Trace API よりも上限が柔軟であるため、Telemetry API を使用することをおすすめします。

  2. [有効な API とサービス] ページに移動し、Cloud Trace API と Telemetry API の行を見つけます。

    これらの 2 つの API の [リクエスト] の数がゼロの場合、プロジェクトにトレースデータが送信されていません。

アプリケーションにトレーススパンを書き込むために必要な権限があることを確認する

アプリケーションにプロジェクトにトレースデータを書き込む権限があるかどうかを確認するには、次の操作を行います。

  1. [有効な API とサービス] ページに移動し、Cloud Trace API と Telemetry API の行を見つけて、[エラー] 列を確認します。

  2. いずれかの API の [エラー] 列にゼロ以外の値が表示されている場合は、その API を介してトレースデータの読み取りまたは書き込みを行う際にエラーが発生しています。エラーのタイプを特定するには、API を選択し、[指標] タブを選択して、[API メソッド別のエラー数] を確認します。

    書き込みが失敗した場合は、認証情報を提供するサービス アカウントに次のロールを付与します。

トレースデータが保存されていることを確認する

トレーススパンは、_Trace という名前のオブザーバビリティ バケットに保存されます。このバケットは、 Google Cloud プロジェクトがトレース スパンを受信したときに自動的にプロビジョニングされます。ただし、プロビジョニングが失敗するシナリオがいくつかあります。

トレースデータにオブザーバビリティ バケットが存在するかどうかを確認するには、[オブザーバビリティ バケットを一覧表示する][trace-storage-list-buckets]か、[Trace エクスプローラ] ページを開きます。たとえば、次の操作が可能です。

  1. Google Cloud コンソールで、 Trace エクスプローラ ページに移動します。

    [Trace エクスプローラ] に移動

    このページは、検索バーを使用して見つけることもできます。

  2. 次のようなバナーが表示された場合は、トレースデータのストレージがプロビジョニングされていないことを示しています。

    Trace storage is not initialized for this project. Enable trace storage to begin collecting trace data.

    トレースデータのオブザーバビリティ バケットをプロビジョニングするには、バナーに移動して [有効にする] をクリックします。

    [有効にする] をクリックすると、そのアクションによってスパンがプロジェクトに送信されます。システムがスパンを受信すると、_Trace という名前のオブザーバビリティ バケットを作成するコマンドが発行されます。このプロセスには数分かかることがあります。

    初期化が成功すると、通知バナーが表示され、Cloud Trace は過去 1 時間に送信されたトレースデータを取り込みます。このデータは一時バッファに保存されていました。データが Trace エクスプローラに表示されるまでに数分かかることがあります。データが表示されない場合は、ウィンドウを更新します。

  3. enable コマンドが失敗すると、次のメッセージが表示されます。

    Initializing trace storage has failed for an unexpected reason. Please file a support ticket for assistance.

    障害を解決するには、[チケットを送信] をクリックして Google Cloud サポートにお問い合わせください。

特定のトレースの検索が失敗する

[Trace エクスプローラ] ページにトレース ID を入力します。トレースが見つからず、次のようなメッセージが表示されます。

The select trace with ID abcde does not exist or is older than 30 days and has been deleted per our retention policy.

この問題を解決するには、次のことを試してください。

  1. トレース ID に関連付けられたタイムスタンプが保持期間内であることを確認します。

  2. トレースを保存する Google Cloud プロジェクトを特定し、 Google Cloud コンソールのリソース選択ツールでこのプロジェクトが選択されていることを確認します。デフォルトでは、[Trace エクスプローラ] ページは、選択したプロジェクトに保存されているトレースデータにのみアクセスできます。

[Trace エクスプローラ] ページに古いデータが表示されない

[Trace エクスプローラ] ページを使用しており、最近のデータは表示されるが、期間セレクタを 30 日またはそれ以上の値に設定すると、古いデータが表示されない。

[Trace エクスプローラ] ページには、Cloud Trace のデータ保持期間（30 日）を超える期間のデータは表示されません。

期間セレクタが 30 日以下の場合は、欠落しているデータは、[Trace エクスプローラ] ページでクエリされたデータベースが、期間設定よりも最近作成されたことを示します。たとえば、この値を 20 日に設定しても、最新の 10 日間のデータしか表示されない場合、データベースは 10 日前に作成されたことになります。また、このデータベースには、データベースの作成後に Google Cloud プロジェクトに送信されたトレースのみが含まれます。

不完全なトレースが表示される

[Trace エクスプローラ] ページを開き、表示するスパンを選択します。[詳細] フライアウトにトレースが表示されますが、トレースは完了していません。一部のスパンが表示されない。

スパンが欠落している原因として、次のことが考えられます。

  • [Trace エクスプローラ] ページで、トレースのスパンデータを保存するすべての Google Cloud プロジェクトが検索されない。

  • トレースのスパンデータを保存する Google Cloud プロジェクトの IAM ロールに、トレースデータを表示するために必要な権限が含まれていません。

  • 計測に関する問題があります。たとえば、トレースの一部のスパンのみが Google Cloud プロジェクトに送信された場合などです。

これらの問題を解決するには、次の操作を行います。

  1. [Trace エクスプローラ] ページで、[スコープ] 要素が、選択したトレースのスパンを保存するプロジェクトを一覧表示するトレース スコープに設定されていることを確認します。

    前の手順で特定したプロジェクトを含むトレース スコープがない場合は、既存のトレース スコープを作成または変更します。詳細については、トレース スコープの作成と管理をご覧ください。

  2. スパンデータを保存するプロジェクトに Cloud Trace ユーザー ロール（roles/cloudtrace.user）があることを確認します。

トレースデータを表示する権限がありません

[Trace エクスプローラ] ページに次の通知が表示されます。

You don't have the required permissions to view trace data for one or more projects listed in the trace scope.

このメッセージを解決するには、ツールバーで次の操作を行います。

  1. [Scope] 要素を開き、選択したトレース スコープを確認します。
  2. [範囲を絞り込む] フライアウトで、[範囲を管理] を選択します。
  3. 最初の手順で特定したトレース スコープを見つけ、詳細を開いて Google Cloud プロジェクトのリストを表示します。
  4. トレース スコープ内の各 Google Cloud プロジェクトで、Cloud Trace ユーザー（roles/cloudtrace.user）のロールが付与されていることを確認します。プロジェクトにそのロールが付与されていない場合は、管理者またはプロジェクト オーナーにそのロールの付与を依頼してください。

トレースにスパン ID メッセージが見つからない

トレースに「スパン ID が見つかりません」というメッセージが含まれています。

分散トレース システムでは、不完全なトレースが想定されます。サンプリングされたスパンに、受信されていない別のスパンへの参照が含まれている場合、トレースは不完全です。未解決の参照は、次の理由で発生する可能性があります。

  • 参照されたスパンがサンプリングされていません。
  • 参照されたスパンがサンプリングされましたが、Cloud Trace でまだ受信されていないか、スパンを受信したが保存されていません。

不完全なトレースを表示すると、Cloud Trace のトレースの詳細ペインに「Missing span ID」というメッセージが表示されます。

「スパン ID がありません」というメッセージが常に表示される場合は、次のことをお試しください。

  • 管理するコンポーネントについては、このフィールドが存在する場合、ヘッダーの sampled フラグ フラグを尊重して伝播することを確認します。この設定は、リクエストをサンプリングするように子コンポーネントにヒントを与えます。トレース ヘッダーの詳細については、コンテキスト伝播のプロトコルをご覧ください。

    通常、Google Cloud サービスでは、このヒントが尊重されます。ただし、トレースデータの書き込みレートも制限します。

  • Cloud Service Mesh を使用している場合は、それらの構成におけるトレース コンテキストの伝播についてのガイダンスに従っていることを確認してください。Cloud Service Mesh のガイダンスについては、トレース コンテキストの伝播をご覧ください。

ログデータとトレースデータを関連付けることができない

次のいずれかの操作を行っている場合:

  • トレース スパンを表示していて、関連するログエントリを表示したい。ただし、ログデータが一覧表示されないか、[ログ エクスプローラ] ページを開いてもログエントリが表示されません。

  • ログエントリを表示していて、関連するトレース スパンを表示したい。ただし、ログエントリのオプションを使用して [Trace エクスプローラ] ページを開いても、トレースデータは表示されません。

これらのエラーを解決するには、オブザーバビリティ スコープを構成します。このスコープは、対応するエクスプローラ ページが開いたときに使用するトレーススコープとログスコープを指定します。詳細については、マルチプロジェクト クエリのオブザーバビリティ スコープを構成するをご覧ください。

OpenTelemetry を使用するように Go アプリを更新した後のトレースデータがない

アプリケーションがトレースをキャプチャするためにクライアント ライブラリを使用しており、OpenTelemetry を使用するようにアプリケーションを更新した後、Cloud Trace データが表示されなくなった。

Go 用の Cloud クライアント ライブラリの一部は OpenCensus と統合されているため、OpenCensus ブリッジを使用する必要があります。ブリッジで解決される問題の詳細については、OpenCensus Bridge をご覧ください。

Go 用 Cloud クライアント ライブラリの更新については、問題 #4237 をご覧ください。