ログ分析でテレメトリーをクエリして分析する

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

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

[ログ分析] ページを使用する場合、ログデータ、トレースデータ、または両方のデータ型をクエリするために、リンクされた BigQuery データセットは必要ありません。

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

• ログデータまたはトレースデータを他の BigQuery データセットと結合する。
• [BigQuery Studio] ページや Looker Studio などの別のサービスからログデータまたはトレースデータをクエリする。
• BigQuery 予約スロットでクエリを実行して、ログ分析から実行するクエリのパフォーマンスを改善する。
• SQL クエリの結果をモニタリングするアラート ポリシーを作成する。この機能は、ログデータのクエリ時にのみサポートされます。詳細については、アラート ポリシーを使用して SQL クエリ結果をモニタリングするをご覧ください。

このドキュメントでは、データ型固有のプロセスが必要なリンクされたデータセットの作成方法については説明しません。リンクされたデータセットを作成する方法については、リンクされたデータセットを使用してログデータをクエリするまたはリンクされたデータセットを使用してトレースデータをクエリするをご覧ください。

始める前に

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.

Observability API を有効にします。

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

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

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.

Observability API を有効にします。

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

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

API の有効化

1. [ログ分析] ページの読み込み、トレースデータに対する非公開クエリの作成、実行、保存に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

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

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

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

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

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

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

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

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

   [ログ分析] に移動

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

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

2. [ビュー] メニューで、ビューを選択します。

   クエリするビューを検索するには、[ フィルタ] バーを使用するか、リストをスクロールします。

   • [segment] [ログ] セクションに表示されるログビューは、バケット ID とビュー ID で並べ替えられます。

   • data_table [アナリティクス ビュー] セクションに表示されるアナリティクス ビューは、ビューの場所と ID で並べ替えられます。オブザーバビリティ ビューはパブリック プレビュー版です。

   • トレースビューは 1 つあり、 [トレース] セクションに表示されます。オブザーバビリティ ビューはパブリック プレビュー版です。

     _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 クエリをご覧ください。

   • クエリするビューによって、FROM 句の形式が決まります。

     ログデータ

     ログビューと分析ビューをクエリできます。FROM 句には次の形式を使用します。

     • ログビュー:

       FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
       

     • 分析ビュー:

       FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`
       

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

     • PROJECT_ID: プロジェクトの ID。
     • LOCATION: ログビューまたは分析ビューのロケーション。
     • BUCKET_ID: ログバケットの名前または ID。
     • LOG_VIEW_ID: ログビューの ID。100 文字に制限され、英字、数字、アンダースコア、ハイフンのみを使用できます。
     • ANALYTICS_VIEW_ID: 分析ビューの ID。100 文字以内で、使用できるのは英字、数字、アンダースコア、ハイフンのみです。

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

     トレースデータ

     プレビュー版

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

     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 つ以上の列の値に基づいてデータをグループにまとめることができます。また、集計を使用すると、これらのグループに対して計算を実行して単一の値を返すことができます。

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

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

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

ログデータ

この例では、クエリビルダーを使用してログエントリを重大度とタイムスタンプでグループ化してから、各グループの http_request.response_size フィールドの平均を計算する方法について説明します。

データをグループ化して集計するクエリを作成するには、クエリビルダーのメニューから次の項目を選択します。

1. [列] メニューで、timestamp、severity、http_request.response_size の各フィールドを選択します。

   1. データをグループ化するには、timestamp フィールドをクリックして設定ダイアログを開きます。このダイアログで [グループ条件] オプションを選択し、[切り捨ての粒度] を HOUR に設定します。構文エラーを防ぐために、グループ化が他のすべてのフィールドに自動的に適用されます。グループ化を適用できない無効なフィールドがある場合は、エラー メッセージが表示されます。このエラーを解決するには、メニューから無効なフィールドを削除します。

   2. http_request.response_size フィールドで集計を行うには、このフィールドをクリックして設定ダイアログを開きます。このダイアログで [集計] を選択します。[集計] メニューで [平均] をクリックします。

      注: [集計] オプションを選択すると、列にもグループ化が自動的に適用されます。

2. [フィルタ] メニューで http_request.response_size を追加し、比較演算子を IS NOT NULL に設定します。このフィルタは、response_size 値を含むログエントリに一致します。

   クエリビルダーのメニューは次のようになります。

   

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

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

   +-----------------------------------+----------+---------------+
   | Row | hour_timestamp              | severity | response_size |
   |     | TIMESTAMP                   | STRING   | INTEGER       |
   +-----+-----------------------------+----------+---------------+
   | 1   | 2025-10-06 16:00:00.000 UTC | NOTICE   | 3082          |
   | 2   | 2025-10-06 17:00:00.000 UTC | WARNING  | 338           |
   | 3   | 2025-10-06 16:00:00.000 UTC | INFO     | 149           |
   

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

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC( timestamp, HOUR ) AS hour_timestamp,
  severity,
  -- Compute average response_size.
  AVG( http_request.response_size ) AS average_http_request_response_size
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a response_size.
  http_request.response_size IS NOT NULL
GROUP BY
  -- Group log entries by timestamp and severity.
  TIMESTAMP_TRUNC( timestamp, HOUR ),
  severity
LIMIT
  1000

トレースデータ

プレビュー版

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

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

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

1. [列] メニューで、start_time、name、kind、duration_nano の各フィールドを選択します。
2. 開始時間を 1 時間単位で切り捨てるには、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

スキーマを表示する

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

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

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

   [ログ分析] に移動

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

2. [ビュー] メニューで、ビューを選択します。

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

   ログデータ

   ログビューの場合は、スキームは固定されており、LogEntry に対応しています。分析ビューの場合は、SQL クエリを変更してスキーマを変更できます。

   トレースデータ

   プレビュー版

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

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

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

制限事項

複数のビューをクエリする場合、これらのビューは同じロケーションに存在する必要があります。たとえば、2 つのビューを us-east1 ロケーションに保存する場合、1 つのクエリで両方のビューをクエリできます。us マルチリージョンに保存されている 2 つのビューをクエリすることもできます。ただし、ビューのロケーションが global の場合、そのビューは任意の物理ロケーションに存在できます。したがって、ロケーションが global の 2 つのビュー間の結合が失敗する可能性があります。

ログデータに適用される制限の一覧については、ログ分析の制限をご覧ください。

次のステップ

• SQL クエリ結果をグラフ化する。
• クエリを保存して共有する。
• サンプル SQL クエリ。