トラブルシューティング

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

既知の問題

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

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

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

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

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

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

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

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

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

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

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

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

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

[ログ分析を使ってみる] メッセージが表示される

[ログ分析] ページを開くと、次のようなメッセージが表示されます。

Get started with Log Analytics

ログ分析を使用するには、ウィンドウで [閉じる] をクリックします。

上記のメッセージは、ログ分析を使用するようにアップグレードされたログバケットがない場合に表示されます。ただし、トレースデータはログバケットに保存されません。

複数のビューの結合が失敗する

複数のビューを結合するクエリを作成しましたが、クエリが無効とマークされています。

すべてのビューを結合できるわけではありません。

ビューを結合するには、次の制限が適用されます。

1. ビューのロケーションが次のいずれかを満たしている。

   • すべてのビューが同じロケーションにある。
   • すべてのビューが global または us ロケーションにある。

2. ストレージ リソースで顧客管理の暗号鍵（CMEK）を使用している場合は、 次のいずれかが当てはまる。

   • CMEK を使用するストレージ リソースが同じ Cloud KMS 鍵を使用している。
   • CMEK を使用するストレージ リソースに共通の祖先があり、その祖先がストレージ リソースと同じロケーションにあるデフォルトの Cloud KMS 鍵を指定している。

   1 つ以上のストレージ リソースで CMEK を使用している場合、結合によって生成された一時データは、共通の Cloud KMS 鍵または祖先のデフォルトの Cloud KMS 鍵で暗号化されます。

たとえば、同じロケーションに 2 つのビューがあるとします。次のいずれかに該当する場合、これらのビューを結合できます。

• ストレージ リソースで CMEK を使用していない。
• 1 つのストレージ リソースで CMEK を使用し、もう 1 つは使用していない。
• 両方のストレージ リソースで CMEK を使用し、両方とも同じ Cloud KMS 鍵を使用している。

• 両方のストレージ リソースで CMEK を使用しているが、異なる鍵を使用している。ただし、リソースは、ストレージ リソースと同じロケーションにあるデフォルトの Cloud KMS 鍵を指定する祖先を共有しています。

  たとえば、ログバケットとオブザーバビリティ バケットのリソース階層に同じ組織が含まれているとします。その組織で、ストレージ ロケーションに同じデフォルトの Cloud KMS 鍵を使用して、Cloud Logging とオブザーバビリティ バケットのデフォルトのリソース設定を構成している場合は、これらのバケットのビューを結合できます。

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

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

トレースデータを表示できない理由はいくつか考えられます。

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

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

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

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

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

スパンがプロジェクトに送信されていることを確認するには、次の操作を行います。

1. Cloud Trace API と Telemetry API を有効にします。

   API を有効にするために必要なロール

   API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。ロールを付与する方法を確認する。

   API を有効にする

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

   注: Cloud Trace API を無効にしている、組織のポリシーが存在する場合があります。これらのポリシーにより、API を有効にできません。

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

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

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

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

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

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

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

   • Cloud Trace API: Cloud Trace エージェント ロール（roles/cloudtrace.agent）。
   • Telemetry API: Cloud テレメトリー トレース書き込み（roles/telemetry.tracesWriter）。

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

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

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

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

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

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

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

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

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

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

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

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

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

リージョン間のクエリは対象外です

[Trace エクスプローラ] ページを開くと、次のようなメッセージが表示されます。

Error loading chart data. Cross-regional queries are not supported. The selected scope comprises buckets residing in multiple locations: list of locations.

このエラー メッセージは、[Trace エクスプローラ] ページで、異なるロケーションに保存されているデータのクエリを発行する必要があることを示しています。

この問題を解決するには、次のいずれかを行います。

• トレースデータを、選択したプロジェクトによって保存されたデータに制限します。

  • [Trace エクスプローラ] ページのツールバーに移動し、[スコープ] メニューを開きます。
  • [範囲を絞り込む] フライアウトで、[現在のプロジェクト] を選択します。

• データが同じロケーションに保存されているプロジェクトを一覧表示するトレース スコープを選択します。この変更を行うには、[スコープ] メニューのオプションを使用します。

• 選択したプロジェクトとは異なるロケーションにデータが保存されているプロジェクトを、選択したトレース スコープから削除します。

  • [Trace エクスプローラ] ページのツールバーに移動し、[スコープ] メニューを開きます。
  • [範囲を絞り込む] フライアウトで、[スコープを管理] を選択します。
  • [トレース スコープ] ページで、任意のトレース スコープを編集できます。

  トレースデータの保管場所を確認するには、 List observability buckets コマンドを実行します。パスパラメータでプロジェクトを指定し、LOCATIONにはワイルドカードとして機能するハイフン（(-)）を設定します。

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

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

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

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

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

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

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

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

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

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

次のいずれかを行っています。

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

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

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

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

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

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

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