查詢及分析追蹤記錄

Observability Analytics 可讓您對 Cloud Trace 資料執行 SQL 查詢，找出效能趨勢、產生匯總洞察資料，並以圖表和表格呈現結果。查詢會針對預設的 _AllSpans 檢視表執行，其中包含專案儲存的所有追蹤記錄資料，您可以將結果儲存至自訂資訊主頁。

如要檢查個別追蹤記錄、Span 或 Span 屬性，請使用「Trace Explorer」頁面。詳情請參閱「尋找及探索追蹤記錄」。

關於連結的 BigQuery 資料集

您不需要連結 BigQuery 資料集，即可查詢追蹤記錄資料，或查詢追蹤記錄和記錄資料。在這種情況下，您可以使用「Observability Analytics」頁面。如要瞭解如何查詢記錄資料，請參閱「使用 Observability Analytics 查詢及分析記錄」。

如要執行下列任一操作，則需要連結 BigQuery 資料集：

本文不會說明如何建立連結的 BigQuery 資料集，或如何設定 Observability Analytics，以便在 BigQuery 引擎上執行查詢。如要瞭解這些主題，請參閱「建立連結的 BigQuery 資料集」和「在 BigQuery 引擎上執行追蹤記錄查詢」。

事前準備

  1. 登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

    8.

  8. 如要取得載入「Observability Analytics」頁面、編寫、執行及儲存追蹤記錄資料私人查詢所需的權限，請要求管理員授予您下列 IAM 角色：

    • 針對要查詢的可觀測性檢視表，取得可觀測性檢視表存取子 (roles/observability.viewAccessor) 角色。這個角色支援 IAM 條件，可讓您限制授予特定檢視。如果未在角色授權中附加條件，主體就能存取所有觀測能力檢視畫面。
    • 專案的 Observability Analytics 使用者 (roles/observability.analyticsUser)。這個角色具備儲存及執行私人查詢，以及執行共用查詢所需的權限。

    如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

    您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

顯示結構定義

結構定義定義了資料的儲存方式，包括欄位及其資料類型。這項資訊對您來說很重要，因為結構定義會決定您查詢的欄位，以及是否需要將欄位轉換為不同的資料類型。舉例來說，如要編寫查詢來計算 HTTP 要求的平均延遲時間，您必須瞭解如何存取延遲時間欄位，以及該欄位是以 100 等整數形式儲存，還是以 "100" 等字串形式儲存。如果延遲時間資料是以字串形式儲存，查詢必須先將值轉換為數值，才能計算平均值。

如要找出結構定義，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

    前往「Observability Analytics」(觀測能力分析) 頁面

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 在「Views」(檢視畫面) 選單中，前往 「Traces」(追蹤記錄) 區段，然後選取 _Trace.Spans._AllSpans。

    「結構定義」窗格會更新。如果資料類型為 JSON，Observability Analytics 會自動推論資料欄的欄位。如要查看這些推論欄位在資料中出現的頻率，請按一下 「Options」(選項)，然後選取「View info and description」(查看資訊和說明)。

    如要瞭解結構定義，請參閱「追蹤記錄資料的儲存空間結構定義」。

    如果找不到名為 _Trace.Spans._AllSpans 的檢視表，代表Google Cloud 專案不含名為 _Trace 的觀測能力 bucket。如要瞭解如何解決這項失敗問題，請參閱「追蹤記錄儲存空間初始化失敗」。

查詢追蹤記錄資料

本節說明查詢追蹤記錄資料的方法：

  • 載入系統定義的查詢，編輯並執行查詢。
  • 輸入並執行自訂查詢。例如，您可以貼上或編寫查詢。自訂查詢可以包含彙整、巢狀查詢和其他複雜的 SQL 陳述式。如需範例，請參閱「SQL 查詢範例」。
  • 透過選單選項建立查詢，然後執行查詢。Observability Analytics 會將所選項目轉換為 SQL 查詢，供您查看及編輯。

載入、編輯及執行系統定義的查詢

  1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

    前往「Observability Analytics」(觀測能力分析) 頁面

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 在「Views」(檢視畫面) 選單中，前往 「Traces」(追蹤記錄) 區段，然後選取 _Trace.Spans._AllSpans。

    如果找不到名為 _Trace.Spans._AllSpans 的檢視表，代表Google Cloud 專案不含名為 _Trace 的觀測能力 bucket。如要瞭解如何解決這項失敗問題，請參閱「追蹤記錄儲存空間初始化失敗」。

  3. 執行下列其中一個步驟：

    • 如要載入依賴「查詢建立工具」的系統定義查詢，請確認「查詢」窗格顯示「查詢建立工具」，以便透過選單選項定義查詢。如果顯示 SQL 編輯器，請按一下 「Builder」(建立工具)。

    • 如要載入系統定義的查詢來擷取 JSON 值，請確認「Query」(查詢) 窗格顯示 SQL 編輯器。如果這個窗格顯示「Query Builder」(查詢建立工具)，請按一下 「SQL」。

  4. 在「結構定義」窗格中，依序選取「查詢」和「覆寫」。

    「Query」(查詢) 窗格會顯示系統定義的查詢。如果您選取「Query Builder」(查詢建立工具) 模式，但想查看 SQL 查詢，請按一下 「SQL」。

  5. 選用：修改查詢。

  6. 如要執行查詢，請前往工具列並選取「Run Query」(執行查詢)。

    Observability Analytics 會以表格形式呈現查詢結果。不過，您可以建立圖表，也可以將表格或圖表儲存至自訂資訊主頁。詳情請參閱「以圖表呈現 SQL 查詢結果」。

    如果工具列顯示「Run in BigQuery」(在 BigQuery 中執行)，則必須將 Observability Analytics 切換為使用預設查詢引擎。如要進行這項變更，請在「Query」(查詢) 窗格的工具列中，依序點選 「Settings」(設定) 和「Analytics (default)」(Analytics (預設))。

輸入並執行自訂查詢

如要輸入 SQL 查詢，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

    前往「Observability Analytics」(觀測能力分析) 頁面

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 在「查詢」窗格中，點選 「SQL」。

    • 如要指定日期範圍，建議您使用日期範圍選取器。如果新增指定 timestamp 欄位的 WHERE 子句，該值會覆寫日期範圍選取器中的設定，且該選取器會停用。

    • 如需範例，請參閱「SQL 查詢範例」。

    • SQL 編輯器會顯示 _Trace.Spans._AllSpans 檢視表的完整名稱，格式如下：

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

      上述運算式中的欄位含義如下：

      如果查詢窗格顯示參照 FROM 陳述式的錯誤訊息，表示找不到檢視表。如要瞭解如何解決這項失敗問題，請參閱「指出檢視表不存在的錯誤訊息」。

  3. 如要執行查詢，請前往工具列並選取「Run Query」(執行查詢)。

    Observability Analytics 會以表格形式呈現查詢結果。不過，您可以建立圖表，也可以將表格或圖表儲存至自訂資訊主頁。詳情請參閱「以圖表呈現 SQL 查詢結果」。

    如果工具列顯示「Run in BigQuery」(在 BigQuery 中執行)，則必須將 Observability Analytics 切換為使用預設查詢引擎。如要進行這項變更，請在「Query」(查詢) 窗格的工具列中，依序點選 「Settings」(設定) 和「Analytics (default)」(Analytics (預設))。

建立、編輯及執行查詢

您可以使用「Query Builder」(查詢建立工具) 介面，從選單中選取項目來建立查詢。Observability Analytics 會將所選項目轉換為 SQL 查詢，供您查看及編輯。舉例來說，您可以先使用查詢建立工具介面，然後切換至 SQL 編輯器來調整查詢。

Observability Analytics 一律可將您在查詢建立工具介面中選取的選單項目轉換為 SQL 查詢。不過，並非所有 SQL 查詢都能透過查詢建立工具介面表示。例如，這個介面無法表示含有彙整的查詢。

如要建立查詢，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

    前往「Observability Analytics」(觀測能力分析) 頁面

    如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

  2. 如果「Query」(查詢) 窗格顯示 SQL 編輯器，請選取 「Builder」(建構工具)，開啟「Query Builder」(查詢建立工具) 窗格。

  3. 使用「Source」(來源) 選單選取要查詢的檢視表。您選取的項目會對應至 SQL 查詢中的 FROM 子句。

  4. 選用：使用下列選單限制或設定結果表格的格式：

    • 搜尋所有欄位：搜尋相符的字串。所選項目會對應至 SQL 查詢中的 WHERE 子句。

    • 資料欄：選取結果表格中顯示的資料欄。您選取的項目會對應至 SQL 查詢中的 SELECT 子句。

      在這個選單中選取欄位名稱後，系統會開啟對話方塊。在這個對話方塊中，您可以執行下列操作：

      • 使用選單匯總或分組資料。

        為避免語法錯誤，您對某個資料欄套用的任何匯總和分組，也會自動套用至其他資料欄。如需匯總及分組項目的範例，請參閱「使用查詢建立工具分組及匯總資料」。

      • 將任何類型的值轉換為其他指定的資料類型。詳情請參閱 CAST 說明文件。

      • 使用規則運算式擷取值的子字串。詳情請參閱 REGEXP_EXTRACT 說明文件。

    • 篩選器：如要將查詢限制在包含特定屬性或 Span ID 的 Span，請新增篩選器。選單會列出所有可用的篩選條件選項。所選項目會對應至 SQL 查詢中的 WHERE 子句。

    • 排序依據：設定要排序的資料欄，以及排序方式為遞增或遞減。所選項目會對應至 SQL 查詢中的 ORDER BY 子句。

    • 限制：設定結果表格中的資料列數量上限。您選取的項目會對應至 SQL 查詢中的 LIMIT 子句。

  5. 如要執行查詢，請前往工具列並選取「Run Query」(執行查詢)。

    Observability Analytics 會以表格形式呈現查詢結果。不過，您可以建立圖表，也可以將表格或圖表儲存至自訂資訊主頁。詳情請參閱「以圖表呈現 SQL 查詢結果」。

    如果工具列顯示「Run in BigQuery」(在 BigQuery 中執行)，則必須將 Observability Analytics 切換為使用預設查詢引擎。如要進行這項變更，請在「Query」(查詢) 窗格的工具列中，依序點選 「Settings」(設定) 和「Analytics (default)」(Analytics (預設))。

範例：使用查詢建立工具將資料分組及匯總

在查詢建立工具中選取資料欄時，每個欄位都會顯示選單，您可以在選單中新增分組和匯總。分組功能可讓您根據一或多個資料欄的值，將資料整理成群組，而匯總功能則可讓您對這些群組執行計算，並傳回單一值。

在「Columns」(欄) 元素中選取的每個欄位都有一個附加選單，其中包含下列選項：

  • 無：不依這個欄位分組或匯總。
  • 匯總：將「Columns」元素中列出的欄位分組，但欄位有「匯總」選項時除外。針對這些欄位，請對每個分組中的所有項目執行運算，藉此計算值。這項作業可能是計算欄位的平均值，或計算每個分組中的項目數量等。
  • 分組依據：依「Columns」元素中列出的所有欄位將項目分組。

以下範例說明如何使用查詢建立工具，依開始時間、Span 名稱和 Span 種類將 Span 分組，然後計算每個群組的平均時間長度 (以奈秒為單位)：

  1. 在「Columns」(資料欄) 選單中，選取 start_time、name、kind 和 duration_nano 欄位。
  2. 如要將開始時間截斷至小時，請展開 start_time 欄的選單，然後選取「Group By」(分組依據)。確認精細程度選單已設為「Hour」(小時)。

  3. 按一下「套用」。

    當您為任何資料欄選取「Group By」(分組依據) 時，系統會依所有資料欄將項目分組。在本例中，項目會依 start_time 的截斷值、Span 名稱、Span 種類和時間長度值分組。

    不過，本範例的目標是依據截斷時間、Span 名稱和 Span 種類將項目分組，然後計算每個群組的平均時間長度。在下一個步驟中，您將修改分組並新增匯總。

  4. 展開「duration_nano」欄位的選單，選取「Aggregate」(匯總)，然後將「Aggregation」(匯總) 欄位設為「Average」(平均值)。

    執行查詢時，每個資料列都會對應至一個群組，其中包含截斷時間、Span 名稱和 Span 種類。每列的最後一個項目是該群組中所有項目的平均時間長度。

    這項查詢的結果大致如下：

    +-----------------------------------+----------------+----------+-----------------------+
| Row | hour_timestamp              | span_name      | kind     | average_duration_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. 在對話方塊中，選取「Aggregate」(匯總)，然後在「Aggregation」(匯總) 中選取「Count」(計數)，接著選取「Apply」(套用)。

    這項異動不會影響分組。項目會依據截斷的開始時間、Span 名稱和 Span 種類分組。不過，查詢會計算每個群組的平均時間長度和項目數量。

上述範例對應的 SQL 查詢如下：

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.us._Trace.Spans._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

後續步驟