トレースのクエリと分析

プレビュー

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

このドキュメントでは、SQL ベースのクエリ インターフェースを提供する ログ分析を使用して、トレースデータをクエリして分析する方法について説明します。SQL を使用すると、集計分析を実行して、分析情報を生成し、傾向を特定できます。クエリ結果を表示するには、表またはグラフを使用します。これらの表とグラフは、カスタム ダッシュボードに保存することもできます。

個々のトレースやスパンを表示または調査する場合や、スパンにアタッチされている属性を表示する場合は、[Trace エクスプローラ] ページを使用します。このページの詳細については、 トレースを検索して調査するをご覧ください。

トレースの場合、_Trace という名前のオブザーバビリティ バケットに対してクエリを実行できます。1 つのビュー _AllSpans を使用してクエリを実行できます。トレースデータの保存方法の詳細については、 ストレージの概要をご覧ください。

リンクされた BigQuery データセットについて

トレースデータやトレースデータとログデータをクエリする場合、リンクされた BigQuery データセットは必要ありません。このような場合は、[ログ分析] ページを使用できます。ログデータのクエリについては、 ログ分析でログのクエリと分析を行うをご覧ください。

次のいずれかを行う場合は、リンクされた BigQuery データセットが必要です。

• トレースデータを他の BigQuery データセットと結合する。
• [BigQuery Studio] ページや Looker Studio などの別のサービスからトレースデータをクエリする。
• BigQuery 予約スロットでクエリを実行して、ログ分析 から実行するクエリのパフォーマンスを改善する 。

このドキュメントでは、リンクされたデータセットを作成する方法や、予約済みスロットでクエリを実行するようにログ分析 を構成する方法については説明しません。 これらのトピックについては、 リンクされた BigQuery データセットに対してクエリを実行するをご覧ください。

始める前に

アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $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. [**ログ分析**] ページを読み込み、トレースデータに対して非公開クエリを作成、実行、保存するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼します。

   • オブザーバビリティ閲覧アクセサー （roles/observability.viewAccessor）クエリを実行するオブザーバビリティ ビューに対する このロールは IAM 条件をサポートしているため、特定のビューへの付与を制限できます。ロール付与に条件をアタッチしない場合、プリンシパルはすべてのオブザーバビリティ ビューにアクセスできます。
   • オブザーバビリティ分析ユーザー （roles/observability.analyticsUser）プロジェクトに対する。このロールには、非公開クエリの保存と実行、共有クエリの実行に必要な権限が含まれています。
   • ログビューア （roles/logging.viewer）プロジェクトに対する。

   ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

スキーマを表示する

スキーマは、フィールドとそのデータ型を含むデータの保存方法を定義します。クエリするフィールドと、フィールドを別のデータ型にキャストする必要があるかどうかがスキーマによって決まるため、この情報は重要です。たとえば、HTTP リクエストの平均レイテンシを計算するクエリを作成するには、レイテンシ フィールドにアクセスする方法と、そのフィールドが整数（100 など）として保存されるか、文字列（"100" など）として保存されるかを把握しておく必要があります。レイテンシ データが文字列として保存される場合、クエリでは平均を計算する前に値を数値に型変換する必要があります。

スキーマを特定するには、次の操作を行います。

1. コンソールで、 [ログ分析] ページに移動します。 Google Cloud

   [ログ分析] に移動

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

2. [ビュー] メニューで、 [トレース] セクションに移動し、 _Trace.Spans._AllSpans を選択します。

   [スキーマ] ペインが更新されます。データ型が JSON の場合、ログ分析は列のフィールドを自動的に推測します。これらの推定フィールドがデータに出現する頻度を確認するには、 [オプション] をクリックして、 [情報と説明を表示] を選択します。

   スキーマについては、 トレースデータのストレージ スキーマをご覧ください。

   _Trace.Spans._AllSpans という名前のビューが表示されない場合、 Google Cloud プロジェクトに _Trace という名前のオブザーバビリティバケットが含まれていません。このエラーの解決方法については、 トレース ストレージの初期化が失敗するをご覧ください。

トレースデータをクエリする

このセクションでは、トレースデータのクエリに使用できるアプローチについて説明します。

• システム定義のクエリを読み込み、このクエリを編集して実行する。
• カスタムクエリを入力して実行する。たとえば、既存のクエリを貼り付けたり、クエリを作成したりできます。カスタムクエリには、結合、ネストされたクエリ、その他の複雑な SQL ステートメントを含めることができます。例については、サンプル SQL クエリをご覧ください。
• メニューから選択してクエリを作成し、そのクエリを実行する。ログ分析では、選択内容が SQL クエリに変換されます。このクエリは表示、編集できます。

システム定義クエリを読み込み、編集、実行する

1. コンソールで、 [ログ分析] ページに移動します。 Google Cloud

   [ログ分析] に移動

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

   注: [ログ分析] ページに [ログ分析を始める] メッセージが表示された場合は、ウィンドウで [ 閉じる] をクリックします。

2. [ビュー] メニューで、 [トレース] セクションに移動し、 _Trace.Spans._AllSpans を選択します。

   _Trace.Spans._AllSpans という名前のビューが表示されない場合、 Google Cloud プロジェクトに _Trace という名前のオブザーバビリティバケットが含まれていません。このエラーの解決方法については、 トレース ストレージの初期化が失敗するをご覧ください。

3. 次のいずれかを行います。

   • クエリビルダーに依存するシステム定義のクエリを読み込むには、[クエリ] ペインに [クエリビルダー] が表示されていることを確認します。クエリビルダーでは、メニューから選択する操作でクエリを定義できます。SQL エディタが表示されたら、[ ビルダー] をクリックします。

   • JSON 値を抽出するシステム定義のクエリを読み込むには、[クエリ] ペインに SQL エディタが表示されていることを確認します。このペインに [クエリビルダー] が表示されている場合は、[ SQL] をクリックします。

4. [スキーマ] ペインで [クエリ] を選択し、[上書き] をクリックします。

   [クエリ] ペインに、システム定義のクエリが表示されます。[クエリビルダー] モードを選択したが SQL クエリを表示したい場合は、[ SQL] をクリックします。

5. 省略可: クエリを変更します。

6. クエリを実行するには、ツールバーに移動して [クエリを実行] を選択します。

   ログ分析では、クエリ結果が表形式で表示されます。ただしグラフを作成することができます。表またはグラフをカスタム ダッシュボードに保存することもできます。詳細については、SQL クエリの結果をグラフ化するをご覧ください。

   ツールバーに [BigQuery で実行] と表示されている場合は、デフォルトのクエリエンジンを使用するようにログ分析を切り替える必要があります。この変更を行うには、[クエリ] ペインのツールバーで [ 設定] をクリックし、[分析（デフォルト）] を選択します。

カスタムクエリを入力して実行する

SQL クエリを入力するには、次の操作を行います。

1. コンソールで、 [ログ分析] ページに移動します。 Google Cloud

   [ログ分析] に移動

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

   注: [ログ分析] ページに [ログ分析を始める] メッセージが表示された場合は、ウィンドウで [ 閉じる] をクリックします。

2. [クエリ] ペインで  [SQL] をクリックします。

   • 期間を指定する場合は、期間セレクタを使用することをおすすめします。timestamp フィールドを指定する WHERE 句を追加する場合、その値は期間セレクタの設定をオーバーライドし、そのセレクタは無効になります。

   • 例については、サンプル SQL クエリをご覧ください。

   • SQL エディタには、_Trace.Spans._AllSpans ビューの完全修飾された名前が次の形式で表示されます。

     FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
     

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

     • PROJECT_ID: プロジェクトの ID。
     • LOCATION: オブザーバビリティ バケットのロケーション。

     クエリペインに FROM ステートメントを参照するエラー メッセージが表示される場合、そのビューが見つかりません。 このエラーの解決方法については、 ビューが存在しないことを示すエラー メッセージをご覧ください。

3. クエリを実行するには、ツールバーに移動して [クエリを実行] を選択します。

   ログ分析では、クエリ結果が表形式で表示されます。ただしグラフを作成することができます。表またはグラフをカスタム ダッシュボードに保存することもできます。詳細については、SQL クエリの結果をグラフ化するをご覧ください。

   ツールバーに [BigQuery で実行] と表示されている場合は、デフォルトのクエリエンジンを使用するようにログ分析を切り替える必要があります。この変更を行うには、[クエリ] ペインのツールバーで [ 設定] をクリックし、[分析（デフォルト）] を選択します。

クエリを作成、編集、実行する

クエリビルダー インターフェースでは、メニューから選択してクエリを作成できます。ログ分析では、選択内容が SQL クエリに変換されます。このクエリを表示して編集できます。たとえば、クエリビルダー インターフェースを使用して開始し、SQL エディタに切り替えてクエリを調整できます。

ログ分析では常に、クエリビルダー インターフェースでメニューから選択した内容を SQL クエリに変換できます。ただし、すべての SQL クエリを クエリビルダー インターフェースで表現できるわけではありません。たとえば、結合を含むクエリをこのインターフェースで表現することはできません。

注: クエリするフィールドがクエリビルダー インターフェースに表示されない場合があります。列のデータ型が JSON の場合、ログ分析では列のフィールドが自動的に推測されます。自動的に推測されなかった JSON フィールドをクエリで使用する場合は、SQL エディタに切り替えてクエリを作成します。

クエリを作成する手順は次のとおりです。

1. コンソールで、 [ログ分析] ページに移動します。 Google Cloud

   [ログ分析] に移動

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

   注: [ログ分析] ページに [ログ分析を始める] メッセージが表示された場合は、ウィンドウで [ 閉じる] をクリックします。

2. [クエリ] ペインに SQL エディタが表示されている場合は、 [ビルダー] を選択します。これにより、[クエリビルダー] ペインが開きます。

3. [ソース] メニューを使用して、クエリするビューを選択します。選択内容は、SQL クエリの FROM 句にマッピングされます。

4. 省略可: 次のメニューを使用して、結果テーブルを制限または形式設定します。

   • すべてのフィールドを検索: 一致する文字列を検索します。選択内容は、SQL クエリの WHERE 句にマッピングされます。

   • 列: 結果テーブルに表示する列を選択します。選択内容は、SQL クエリの SELECT 句にマッピングされます。

     このメニューでフィールド名を選択すると、ダイアログが開きます。このダイアログでは次の操作が可能です。

     • メニューを使用して、データを集計またはグループ化します。

       構文エラーを回避するため、1 つの列に適用された集計とグループ化は、他の列にも自動的に適用されます。エントリを集計してグループ化する方法の例については、クエリビルダーを使用してデータをグループ化して集計するをご覧ください。

     • 任意の型の値を別の指定されたデータ型にキャストします。詳細については、CAST のドキュメントをご覧ください。

     • 正規表現を使用して値の部分文字列を抽出します。詳細については、REGEXP_EXTRACT のドキュメントをご覧ください。

   • フィルタ: 特定の属性またはスパン ID を含むスパンにクエリを制限するには、フィルタを追加します。メニューには、使用可能なすべてのフィルタ オプションが表示されます。選択内容は、SQL クエリの WHERE 句にマッピングされます。

   • 並べ替え: 並べ替える列と、並べ替えの昇順または降順を設定します。選択内容は、SQL クエリの ORDER BY 句にマッピングされます。

   • 上限: 結果テーブルの最大行数を設定します。選択内容は、SQL クエリの LIMIT 句にマッピングされます。

5. クエリを実行するには、ツールバーに移動して [クエリを実行] を選択します。

   ログ分析では、クエリ結果が表形式で表示されます。ただしグラフを作成することができます。表またはグラフをカスタム ダッシュボードに保存することもできます。詳細については、SQL クエリの結果をグラフ化するをご覧ください。

   ツールバーに [BigQuery で実行] と表示されている場合は、デフォルトのクエリエンジンを使用するようにログ分析を切り替える必要があります。この変更を行うには、[クエリ] ペインのツールバーで [ 設定] をクリックし、[分析（デフォルト）] を選択します。

例: クエリビルダーを使用してデータをグループ化して集計する

クエリビルダーで列を選択すると、グループ化と集計を追加できるメニューが各フィールドに表示されます。グループ化を使用すると、1 つ以上の列の値に基づいてデータをグループにまとめることができます。また、集計を使用すると、これらのグループに対して計算を実行して単一の値を返すことができます。

[列] 要素で選択した各フィールドには、次のオプションを含むメニューが関連付けられています。

• なし: このフィールドでグループ化または集計を行いません。
• 集計: フィールドで [集計] が選択されている場合を除き、[列] 要素にリストされているフィールドはグループ化されます。これらのフィールドでは、各グループのすべてのエントリに対してオペレーションが実行され、値が計算されます。オペレーションは、フィールドの平均値の計算や、各グループのエントリ数のカウントなどの操作です。
• グループ条件: [列] 要素にリストされているすべてのフィールドでエントリをグループ化します。

次の例は、エントリをグループ化してからなんらかの集計を行うクエリを作成する方法を示しています。

この例では、クエリビルダーを使用して、開始時間、スパン名、スパンの種類でスパンをグループ化する方法について説明します。次に、各グループについて、クエリは平均継続時間をナノ秒単位で計算します。

このクエリを作成するには、次の操作を行います。

1. [列] メニューで、start_time、name、kind、duration_nano の各フィールドを選択します。
2. 開始時間を切り捨てて時間単位にするには、start_time 列のメニューを開き、[グループ条件] を選択します。粒度メニューが [時間] に設定されていることを確認します。

3. [適用] をクリックします。

   任意の列で [グループ条件] を選択すると、システムはすべての列でエントリをグループ化します。この例では、エントリは、切り捨てられた start_time の値、スパン名、スパンの種類、継続時間の値でグループ化されます。

   ただし、この例の目的は、切り捨てられた時間、スパン名、スパンの種類でエントリをグループ化し、各グループの平均継続時間を計算することです。次のステップでは、グループ化を変更して集計を追加します。

4. duration_nano フィールドのメニューを開き、[**集計**] を選択して、 [**集計**] フィールドを [**平均**] に設定します。

   クエリを実行すると、各行は、切り捨てられた時間、スパン名、スパンの種類で構成されるグループに対応します。各行の最後のエントリは、そのグループ内のすべてのエントリの平均継続時間です。

   このクエリの結果は次のようになります。

   +-----------------------------------+----------------+----------+-----------------------+
   | Row | hour_timestamp              | span_name      | kind     | average_duation_nano  |
   |     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
   +-----+-----------------------------+-----------+---------------+-----------------------+
   | 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
   | 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
   | 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376
   

5. クエリには複数の集計を含めることができます。たとえば、各グループのエントリ数をカウントする列を追加するには、次の操作を行います。

   1. [列] 要素で、[列を追加] をクリックします。
   2. [すべて（*）] を選択します。
   3. ダイアログで、[**集計**] を選択し、[**カウント**] を [**集計**] に選択して、[**適用**] を選択します。

   この変更では、グループ化は変わりません。エントリは、切り捨てられた開始時間、スパン名、スパンの種類でグループ化されます。ただし、各グループについて、クエリは平均継続時間とエントリ数を計算します。

前の例に対応する SQL クエリは次のとおりです。

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.global._Trace._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

次のステップ

• SQL クエリを保存して共有する。
• SQL クエリ結果をグラフ化する。
• サンプル SQL クエリ。
• BigQuery でリンクされたデータセットに対してクエリを実行する。