トレース スコープを作成して管理する

このドキュメントでは、トレーススコープを作成して管理する方法について説明します。トレーススコープを使用すると、トレース エクスプローラ ページで、表示または分析するトレース スパンを見つけることができます。 Google Cloud プロジェクトで発生したスパンのみを表示して分析する場合は、トレース スコープを構成する必要はありません。ただし、マイクロサービス アーキテクチャを使用する場合のように、トレースデータが複数のプロジェクトに保存されている場合は、1 つのプロジェクトからすべてのスパンを表示するために、いくつかの構成アクティビティを実行する必要があります。 Google Cloud

このドキュメントでは、トレースとスパンを表示する方法については説明しません。このトピックについては、トレースを検索して調査するをご覧ください。

この機能は Google Cloud プロジェクトでのみサポートされています。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。

トレース スコープについて

トレース スコープは、トレースデータへのアクセスを提供するビューを一覧表示するプロジェクト レベルの永続的なリソースです。トレース スコープで検索するように Trace エクスプローラ ページを構成できます。つまり、選択したスコープに一覧表示されているビューがページで検索されます。システムがストレージからフェッチして表示するデータは、検索対象のビューに対する Identity and Access Management（IAM）ロールと期間の設定によって決まります。

トレース スコープを作成できます。また、作成したトレース スコープは変更および削除できます。複数の Google Cloud プロジェクトにスパンデータを書き込むサービスがある場合は、トレース スコープを作成します。

トレース スコープには、 Google Cloud プロジェクトではなくビューが一覧表示されます。トレース スコープを構成するときにプロジェクトを選択しますが、システムはそれらのプロジェクトのデフォルトのトレースビューをスコープに追加します。プロジェクトのデフォルトのトレースビューは、パス _Trace/Spans/_AllSpans のビューに対応します。ここで、フィールド _Trace、Spans、_AllSpans は、オブザーバビリティ バケット、データセット、ビューを参照します。データセット Spans にトレースデータが保存されます。

トレース スコープまたはトレースとスパン ID を含む URL で [Trace エクスプローラ] ページを開かない限り、[Trace エクスプローラ] ページは、デフォルトのトレース スコープにリストされているビューでトレースデータを検索します。プロジェクトを作成すると、_Default という名前のトレース スコープがデフォルトのトレース スコープとして設定されます。ただし、別のトレース スコープを選択して、デフォルトのトレース スコープとして使用できます。

オブザーバビリティ スコープについて

オブザーバビリティ スコープは、対応するエクスプローラ ページが開いたときに使用するトレース スコープとログスコープを指定します。データを保存するリソースを一覧表示するようにオブザーバビリティ スコープを構成しないと、トレースデータとログデータを関連付けられない可能性があります。詳細については、マルチプロジェクト クエリのオブザーバビリティ スコープを構成するをご覧ください。

App Hub のアプリケーションとトレーススコープ

App Hub アプリケーションは、トレースデータを複数のプロジェクトに書き込む場合があります。このデータの集計ビューを取得するには、トレース スコープを作成し、トレースデータを保存するすべてのプロジェクトのデフォルトのトレースビューを一覧表示するように構成してから、デフォルトのトレース スコープとして構成します。これらの手順を完了すると、アプリケーションによって書き込まれたデータが [Trace エクスプローラ] ページに自動的に表示されます。このデータは、異なるプロジェクトに保存されている場合でも表示されます。

トレースデータを表示するプロジェクトにカスタム トレース スコープを作成します。このプロジェクトは、App Hub ホスト プロジェクトまたは管理プロジェクトです。たとえば、フォルダの表示名が My Folder の場合、フォルダの管理プロジェクトの表示名は My Folder-mp になります。

始める前に

Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

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 API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

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 API

1. トレース スコープの作成と表示に必要な権限を取得するには、プロジェクトに対するオブザーバビリティ スコープ編集者 （roles/observability.scopesEditor）の IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

   必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

   オブザーバビリティ スコープ編集者のロールには、トレース スコープの作成と表示を可能にする非公開権限が含まれています。これらの権限は、カスタム IAM ロールに含めることはできません。

2. このページのサンプルをどのように使うかに応じて、タブを選択してください。

   コンソール

   Google Cloud コンソールを使用して Google Cloud サービスと API にアクセスする場合、認証を設定する必要はありません。

   gcloud

   Google Cloud コンソールで Cloud Shell をアクティブにします。

   Cloud Shell をアクティブにする

   Google Cloud コンソールの下部にある Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

   Terraform

   ローカル開発環境でこのページの Terraform サンプルを使用するには、gcloud CLI をインストールして初期化し、ユーザー認証情報を使用してアプリケーションのデフォルト認証情報を設定します。

   1. Google Cloud CLI をインストールします。

   2. 外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

   3. ローカルシェルを使用している場合は、ユーザー アカウントのローカル認証情報を作成します。

      gcloud auth application-default login

      Cloud Shell を使用している場合は、この操作を行う必要はありません。

      認証エラーが返され、外部 ID プロバイダ（IdP）を使用している場合は、 連携 ID を使用して gcloud CLI にログインしていることを確認します。

   詳細については、 Google Cloud 認証ドキュメントの ローカル開発環境の ADC の設定をご覧ください。

   REST

   このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

   Google Cloud CLI をインストールします。

   外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

   詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

トレース スコープを一覧表示する

コンソール

トレーススコープを一覧表示するには、次の操作を行います。

1. Google Cloud コンソールで [ 設定] ページに移動します。

   [設定] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。

3. [トレース スコープ] タブを選択します。

   ウィンドウにトレース スコープのリストが表示されます。「デフォルト」アイコン が含まれているエントリがデフォルトのトレース スコープです。

4. トレース スコープの詳細を表示するには、トレース スコープを開きます。

   トレース スコープを展開すると、スコープに含まれるビューのリストが表示されます。各行には、プロジェクト ID と _Trace/Spans/_AllSpans などのエントリが一覧表示されます。このエントリは、トレースデータのデフォルトの保存場所を識別します。_Trace、Spans、_AllSpans の各フィールドは、トレースデータのオブザーバビリティ バケット、データセット、ビューを参照します。_AllSpans ビューは、バケット内のすべてのエントリに対応しています。

   名前	説明	タイプ	リソース
   _Default		Trace scope	1
   myscope	My description	Trace scope	2
   _Trace/Spans/_AllSpans	myproject	Trace view
   _Trace/Spans/_AllSpans	project-b	Trace view

gcloud

サポートされていません。

Terraform

Terraform を使用してトレーススコープの作成と変更を行うことができます。ただし、Terraform を使用してトレーススコープを一覧表示することはできません。

REST

プレビュー

このプロダクトまたは機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

Google Cloud プロジェクト内のすべてのトレーススコープを一覧表示するには、projects.locations.traceScopes.list コマンドを使用します。パスパラメータを指定する必要があります。

このエンドポイントのパスパラメータの構文は次のとおりです。

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

前の式のフィールドの意味は次のとおりです。

• PROJECT_ID: プロジェクトの ID。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
• LOCATION_ID は global に設定する必要があります。

レスポンスは TraceScope オブジェクトの配列です。各オブジェクトには、名前とリソースのリストが含まれます。

特定のトレース スコープに関する情報を取得するには、projects.locations.traceScopes.get コマンドを使用します。

トレース スコープを作成する

[Trace エクスプローラ] ページに表示されるスパンは、検索されたビュー、それらのビューに対する IAM ロール、期間の設定、適用するフィルタによって異なります。

警告: トレース スコープにリストされているすべてのビューが、同じロケーションにトレースデータを保存していることを確認してください。システムは、トレースデータを _Trace という名前のオブザーバビリティ バケットに保存します。トレースデータが保存されている場所を表示する方法については、オブザーバビリティ バケットを一覧表示するをご覧ください。

プロジェクトごとに作成できるトレース スコープは 100 個までです。トレース スコープに含めることができるビューは合計 20 個です。

コンソール

トレース スコープを作成する手順は次のとおりです。

1. Google Cloud コンソールで [ 設定] ページに移動します。

   [設定] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
3. [トレースのスコープ] タブを選択し、[トレースのスコープを作成] をクリックします。

4. [プロジェクトを追加] をクリックして、ダイアログを完了します。

   注: プロジェクトを選択すると、プロジェクトのデフォルトのトレースビューがスコープに追加されます。

5. [トレース スコープの指定] セクションで、[トレース スコープ] タブに表示する名前と説明を入力します。

   トレース スコープの名前は変更できません。また、プロジェクト内で一意にする必要があります。

6. [トレーススコープを作成] をクリックします。

   デフォルトでは、[トレース スコープ] テーブルにトレース スコープが折りたたまれた形式で一覧表示されます。各スコープについて、名前、説明、タイプ、リソースの数が表に示されます。

   トレース スコープを展開すると、スコープに含まれるビューのリストが表示されます。各行には、プロジェクト ID と _Trace/Spans/_AllSpans などのエントリが一覧表示されます。このエントリは、トレースデータのデフォルトの保存場所を識別します。_Trace、Spans、_AllSpans の各フィールドは、トレースデータのオブザーバビリティ バケット、データセット、ビューを参照します。_AllSpans ビューは、バケット内のすべてのエントリに対応しています。

   名前	説明	タイプ	リソース
   _Default		Trace scope	1
   myscope	My description	Trace scope	2
   _Trace/Spans/_AllSpans	myproject	Trace view
   _Trace/Spans/_AllSpans	project-b	Trace view

gcloud

サポートされていません。

Terraform

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。詳細については、Terraform プロバイダのリファレンス ドキュメントをご覧ください。

Terraform を使用してプロジェクトにトレーススコープを作成する手順は次のとおりです。

1. google_observability_trace_scope Terraform リソースを使用します。

   コマンドで、次のフィールドを設定します。

   • project: プロジェクト、フォルダ、または組織の名前。例: my-projectApp Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。

     注: プロジェクトを選択すると、そのプロジェクトの Spans データセットの _AllSpans ビューが表示されます。_AllSpans ビューがスコープに追加されます。

   • provider: google-beta に設定します。

   • trace_scope_id: スコープ ID に設定します。例: my-trace-scope

   • location: "global" に設定します。

   • resource_names: プロジェクトの配列。各プロジェクトは完全修飾名で指定します。

   • description: 簡単な説明。たとえば、「本番環境リソースのスコープ」などです。

2. main.tf ファイルを更新したら、Terraform のインストールをアップグレードします。

   terraform -init upgrade
   

   google_observability_trace_scope リソースがベータ版であるため、アップグレードが必要です。

REST

プレビュー

このプロダクトまたは機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

トレース スコープを作成するには、projects.locations.traceScopes.create コマンドを使用します。パスパラメータを指定し、TraceScope オブジェクトを指定する必要があります。レスポンスは TraceScope オブジェクトです。

このエンドポイントのパスパラメータの構文は次のとおりです。

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

前の式のフィールドの意味は次のとおりです。

• PROJECT_ID: プロジェクトの ID。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
• LOCATION_ID は global に設定する必要があります。

トレーススコープを変更または削除する

_Default という名前のトレース スコープを削除または変更することはできません。他のすべてのトレース スコープは変更または削除できます。

コンソール

トレーススコープを変更または削除する手順は次のとおりです。

1. Google Cloud コンソールで [ 設定] ページに移動します。

   [設定] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
3. [トレース スコープ] タブを選択します。

4. 変更または削除するトレース スコープを見つけて、[ その他] をクリックしてから、次のいずれかを行います。

   • 変更するには、[スコープの編集] を選択して、ダイアログを完了します。
   • 削除するには、[スコープの削除] を選択して、ダイアログを完了します。

gcloud

サポートされていません。

Terraform

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。詳細については、Terraform プロバイダのリファレンス ドキュメントをご覧ください。

Terraform を使用してプロジェクトのトレース スコープを変更する手順は次のとおりです。

1. google_observability_trace_scope Terraform リソースを使用します。

2. main.tf ファイルを更新したら、Terraform のインストールをアップグレードします。

   terraform -init upgrade
   

   google_observability_trace_scope リソースがベータ版であるため、アップグレードが必要です。

REST

スコープを変更する

プレビュー

このプロダクトまたは機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

トレース スコープを変更するには、projects.locations.traceScopes.patch コマンドを使用します。パスパラメータとクエリ パラメータを指定し、TraceScope オブジェクトを指定する必要があります。クエリ パラメータは、変更されるフィールドを特定します。レスポンスは TraceScope オブジェクトです。

このエンドポイントのパスパラメータの構文は次のとおりです。

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

前の式のフィールドの意味は次のとおりです。

• PROJECT_ID: プロジェクトの ID。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
• LOCATION_ID は global に設定する必要があります。
• TRACE_SCOPE_NAME: トレース スコープの名前。例: my-trace-scope

スコープを削除する

プレビュー

このプロダクトまたは機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

トレース スコープを削除するには、projects.locations.traceScopes.delete コマンドを使用します。パスパラメータを指定する必要があります。

このエンドポイントのパスパラメータの構文は次のとおりです。

projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

前の式のフィールドの意味は次のとおりです。

• PROJECT_ID: プロジェクトの ID。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
• LOCATION_ID は global に設定する必要があります。
• TRACE_SCOPE_NAME: トレース スコープの名前。例: my-trace-scope

デフォルトのトレース スコープを構成する

[Trace エクスプローラ] ページが開くと、デフォルトのトレース スコープにリストされているビューでトレースデータが検索されます。そのトレース スコープにアクセスできない場合、[Trace エクスプローラ] ページは、デフォルトのデータセットのプロジェクトの _AllSpans ビューにクエリを実行します。

プロジェクトが作成されると、_Default という名前のトレース スコープが作成され、デフォルトのトレース スコープとして指定されます。ただし、独自のトレース スコープを作成して、デフォルトのトレース スコープとして指定することはできます。

コンソール

デフォルトのトレース スコープを設定するには、次の操作を行います。

1. Google Cloud コンソールで [ 設定] ページに移動します。

   [設定] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

2. Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。

3. [トレース スコープ] タブを選択します。

   このタブには、トレース スコープが表示され、カスタム トレース スコープを作成するためのボタンが含まれています。「デフォルト」アイコン が付いているトレース スコープが、現在のデフォルトのトレース スコープです。

4. デフォルトのトレース スコープを変更するには、デフォルトのトレース スコープとして指定するトレース スコープを見つけて、その  [その他] をクリックし、[デフォルトに設定] を選択します。

   選択したトレース スコープにデフォルト アイコン が表示されます。

gcloud

サポートされていません。

Terraform

Terraform を使用してトレーススコープの作成と変更を行うことができます。ただし、Terraform を使用してデフォルトのトレース スコープを設定することはできません。

REST

プレビュー

このプロダクトまたは機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。詳細については、リリース ステージの説明をご覧ください。

API 呼び出しを使用してデフォルトのログスコープまたはデフォルトのトレース スコープを取得して設定するには、オブザーバビリティ スコープを構成します。オブザーバビリティ スコープには、デフォルトのログスコープとデフォルトのトレース スコープがリストで示されます。

• プロジェクトのデフォルトのオブザーバビリティ スコープを取得するには、projects.locations.scopes.get エンドポイントにリクエストを送信します。パスパラメータを指定する必要があります。レスポンスは、デフォルトのログスコープとデフォルトのトレース スコープをリストで示す Scope オブジェクトです。

• プロジェクトのデフォルトのオブザーバビリティ スコープを更新するには、projects.locations.scopes.patch エンドポイントにリクエストを送信します。パスパラメータとクエリ パラメータを指定し、Scope オブジェクトを指定する必要があります。クエリ パラメータは、変更されるフィールドを特定します。レスポンスは Scope オブジェクトです。

どちらのエンドポイントのパスパラメータも次の形式になります。

projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

前の式のフィールドの意味は次のとおりです。

• PROJECT_ID: プロジェクトの ID。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
• LOCATION: ロケーション フィールドは global に設定する必要があります。
• OBSERVABILITY_SCOPE_ID: Scope オブジェクトの名前。このフィールドは _Default に設定する必要があります。_Default という名前の Scope オブジェクト（自動的に作成される）に、デフォルトのログスコープとデフォルトのトレース スコープに関する情報が格納されます。

API エンドポイントにコマンドを送信するには、API Explorer を使用します。API Explorer を使用すると、リファレンス ページからコマンドを実行できます。たとえば、現在のデフォルト スコープを取得するには、次の操作を行います。

1. projects.locations.scopes.get をクリックします。

2. [この方法を試す] ウィジェットの [名前] フィールドに、次のように入力します。

   projects/PROJECT_ID/locations/global/scopes/_Default
   

   前のフィールドをコピーする前に、PROJECT_ID をプロジェクトの名前に置き換えます。

3. [Execute] を選択します。

4. 承認ダイアログで、必要な手順を完了します。

   レスポンスは次の例のようになります。

   {
   "name": "projects/my-project/locations/global/scopes/_Default",
   "logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
   "traceScope": "projects/my-project/locations/global/traceScopes/_Default"
   }
   

トレース スコープの上限

トレース スコープの上限	値
プロジェクトあたりのトレース スコープの最大数	100
トレース スコープあたりの最大ビュー数	20

次のステップ

• トレースの検索と調査

• Cloud Logging と Cloud Monitoring には、表示またはモニタリングできるログデータまたは指標データを制御できる同様の構成が含まれています。これらのスコープについては、次のドキュメントをご覧ください。

  • オブザーバビリティ スコープの概要
  • ログスコープを作成して管理する
  • 指標スコープの概要