Trace のサンプル SQL クエリ

プレビュー

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

このドキュメントには、 Google Cloud プロジェクトに保存されているトレースデータのクエリに固有のサンプルクエリが含まれています。

SQL 言語のサポート

[ログ分析] ページで使用されるクエリは、一部の例外を除き、GoogleSQL 関数をサポートしています。

[ログ分析] ページを使用して発行された SQL クエリでは、次の SQL コマンドはサポートされていません。

• DDL コマンドと DML コマンド
• JavaScript ユーザー定義関数
• BigQuery ML 関数
• SQL 変数

以下は、[BigQuery Studio] ページ、[Looker Studio] ページ、または bq コマンドライン ツールを使用してリンク済みデータセットをクエリする場合にのみサポートされます。

• JavaScript ユーザー定義関数
• BigQuery ML 関数
• SQL 変数

ベスト プラクティス

クエリの期間を設定するには、期間セレクタを使用することをおすすめします。たとえば、過去 1 週間のデータを表示するには、期間セレクタで [過去 7 日間] を選択します。また、期間セレクタを使用して、開始時刻と終了時刻の指定、表示時間の指定、タイムゾーンの変更を行うこともできます。

WHERE 句に start_time フィールドを含めると、期間セレクタの設定は使用されません。次の例では、TIMESTAMP_SUB 関数を使用してデータをフィルタリングします。この関数を使用すると、現在の時刻から遡る間隔を指定できます。

WHERE
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

時間でフィルタする方法の詳細については、時間関数とタイムスタンプ関数をご覧ください。

始める前に

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

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

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

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

このページのクエリの使用方法

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

   [ログ分析] に移動

   このページを検索バーで検索する場合は、小見出しが「Logging」の結果を選択します。

2. [クエリ] ペインで、[ SQL] をクリックし、クエリをコピーして SQL クエリペインに貼り付けます。

   次に、_AllSpans ビューをクエリするための FROM 句の形式を示します。

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

   FROM 句には次のフィールドが含まれます。

   • PROJECT_ID: プロジェクトの ID。
   • LOCATION: オブザーバビリティ バケットのロケーション。
   • _Trace はオブザーバビリティ バケットの名前です。
   • Spans は、データセットの名前です。
   • _AllSpans はビューの名前です。
   注: パスの区切り文字はピリオド (.) です。 Google Cloud プロジェクトなどのパス要素にピリオドが含まれている場合は、すべてのパスフィールドが単一バッククォート (`) で囲まれていることを確認します。

このドキュメントに示すクエリを [BigQuery Studio] ページで使用する場合や、bq コマンドライン ツールを使用する場合は、FROM 句を編集して、リンクされたデータセットへのパスを入力します。たとえば、プロジェクト myproject にある my_linked_dataset という名前のリンクされたデータセットで _AllSpans ビューをクエリする場合、パスは `myproject.my_linked_dataset._AllSpans` です。

一般的なユースケース

このセクションでは、カスタムクエリの作成に役立つ一般的なユースケースをいくつか紹介します。

すべてのトレースデータを表示する

_AllSpans ビューをクエリするには、次のクエリを実行します。

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

共通のスパン情報を表示する

開始時間や期間などの一般的なスパン情報を表示するには、次のクエリを実行します。

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

詳細については、条件式をご覧ください。

スパン レイテンシの 50 パーセンタイルと 99 パーセンタイルを表示する

各 RPC サービスのレイテンシの 50 パーセンタイルと 99 パーセンタイルを表示するには、次のクエリを実行します。

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

列挙型の詳細については、OpenTelemetry: SpanKind のドキュメントをご覧ください。

結果をグラフで表示するには、ディメンションを rpc_service_method に設定したグラフを作成します。たとえば、duration_nano_p50 値の平均値と duration_nano_p99 フィールドの平均値の 2 つの指標を追加できます。

トレース エントリをフィルタする

クエリにフィルタを適用するには、WHERE 句を追加します。この句で使用する構文は、フィールドのデータ型によって異なります。このセクションでは、さまざまなデータ型の例をいくつか示します。

文字列データ型でフィルタする

フィールド name は String として保存されます。

• name が指定されているスパンのみを分析するには、次の句を使用します。

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• name の値が "POST" のスパンのみを分析するには、次の句を使用します。

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• name に値 "POST" が含まれているスパンのみを分析するには、LIKE 演算子とワイルドカードを使用します。

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

整数データ型でフィルタする

フィールド kind は 0 ～ 5 の値をとる整数です。

• kind が指定されているスパンのみを分析するには、次の句を使用します。

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

• kind 値が 1 または 2 のスパンを分析するには、次の句を使用します。

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

RECORD データ型でフィルタする

トレース スキーマの一部のフィールドのデータ型は RECORD です。これらのフィールドには、1 つ以上のデータ構造を保存することも、同じデータ構造の繰り返しエントリを保存することもできます。

ステータスまたはステータス コードでフィルタする

status フィールドは、データ型が RECORD のフィールドの例です。このフィールドには、code と message というラベルの付いたメンバーを含む 1 つのデータ構造が格納されます。

• status.code フィールドの値が 1 の場合にのみスパンを分析するには、次の句を追加します。

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  status.code フィールドは整数として保存されます。

• status フィールドが EMPTY ではないスパンを分析するには、次の句を追加します。

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

イベントまたはリンクでフィルタする

events フィールドと links フィールドは RECORD のデータ型で保存されますが、これらは繰り返しフィールドです。

• 少なくとも 1 つのイベントを含むスパンを照合するには、次の句を使用します。

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• name フィールドの値が message のイベントを含むスパンを照合するには、次の句を使用します。

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

JSON データ型でフィルタする

attributes フィールドの型は JSON です。個々の属性は Key-Value ペアです。

• attributes が指定されているスパンのみを分析するには、次の句を使用します。

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• 属性キー component の値が "proxy" のスパンのみを分析するには、次の句を使用します。

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

  LIKE ステートメントとワイルドカードを使用して、包含テストを行うこともできます。

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

トレースデータをグループ化して集計する

このセクションでは、スパンをグループ化して集計する方法について説明します。グループ化を指定せずに集計を指定する場合は、SQL が WHERE 句を満たすすべてのエントリを 1 つのグループとして扱うため、1 つの結果が出力されます。

すべての SELECT 式は、グループ フィールドに含めるか、集計する必要があります。

スパンを開始時刻でグループ化する

データを開始時刻でグループ化するには、関数 TIMESTAMP_TRUNC を使用します。この関数は、HOUR のような指定した粒度までタイムスタンプを切り詰めます。

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

詳細については、TIMESTAMP_TRUNC のドキュメントと日時関数をご覧ください。

注: WHERE 句に start_time フィールドを含めると、期間セレクタの設定は使用されません。

ステータス コード別にスパンをカウントする

特定のステータス コードを持つスパンの数を表示するには、次のクエリを実行します。

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

status.code を kind に置き換えると、前のクエリは kind 列挙型の各値のスパン数をレポートします。同様に、status.code を name に置き換えると、クエリ結果には各スパン名のエントリ数が表示されます。

すべてのスパンの平均期間を計算する

スパンデータをスパン名でグループ化した後の平均期間を表示するには、次のクエリを実行します。

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

サービス名ごとに平均期間とパーセンタイルを計算する

次のクエリは、各サービスのスパンス数とさまざまな統計情報を計算します。

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

クロスカラム検索

このセクションでは、クエリを実行しているビューの複数の列を検索するために使用できる 2 つの方法について説明します。

• トークンベース検索: 検索場所と検索クエリを指定し、SEARCH 関数を使用します。SEARCH 関数にはデータの検索方法に関する特定のルールがあるため、SEARCH のドキュメントを一読することをおすすめします。

• 部分文字列ベースの検索: 検索場所と文字列リテラルを指定し、CONTAINS_SUBSTR 関数を使用します。システムは、大文字と小文字を区別しないテストを実行して、文字列リテラルが式に存在するかどうかを判断します。CONTAINS_SUBSTR 関数は、文字列リテラルが存在する場合は TRUE を返し、それ以外の場合は FALSE を返します。検索値は STRING リテラルである必要があり、リテラル NULL ではありません。

複数のビューをクエリする

クエリ ステートメントは、1 つ以上のテーブルまたは式をスキャンし、計算結果の行を返します。たとえば、クエリ ステートメントを使用して、さまざまなテーブルやデータセットの SELECT ステートメントの結果をマージし、結合データから列を選択できます。

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

1. ビューの場所は次のいずれかを満たします。

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

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

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

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

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

• ストレージ リソースが CMEK を使用していない。
• 一方のストレージ リソースは CMEK を使用し、もう一方のストレージ リソースは CMEK を使用していません。
• 両方のストレージ リソースが CMEK を使用し、両方とも同じ Cloud KMS 鍵を使用します。

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

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

トレース ID を使用してトレースデータとログデータを結合する

次のクエリは、スパン ID とトレース ID を使用してログデータとトレースデータを結合します。

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

クエリのレスポンスにはトレース ID とスパン ID が一覧表示されます。これらの ID を個別にクエリして、詳細情報を収集できます。また、結果にはログエントリの重大度と JSON ペイロードが一覧表示されます。

次のステップ

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

SQL リファレンス ドキュメントまたはその他の例については、次のドキュメントをご覧ください。

• 関数、演算子、条件。
• 検索関数。
• クエリ構文。
• Cloud Logging のサンプル SQL クエリ。