使用記錄檔分析查詢及分析遙測資料

本文說明如何使用記錄檔分析功能查詢及分析記錄和追蹤資料。這項功能提供以 SQL 為基礎的查詢介面。您可以使用 SQL 執行匯總分析，藉此產生洞察結果並找出趨勢。如要查看查詢結果，請使用表格形式，或以圖表呈現資料。您也可以將這些表格和圖表儲存到自訂資訊主頁。

關於連結的 BigQuery 資料集

使用「記錄分析」頁面時，您不需要連結 BigQuery 資料集，即可查詢記錄資料、追蹤資料或這兩種資料類型。

如要執行下列任一操作，您必須連結 BigQuery 資料集：

• 將記錄或追蹤資料與其他 BigQuery 資料集彙整。
• 從其他服務 (例如 BigQuery Studio 頁面或 Looker Studio) 查詢記錄或追蹤資料。
• 在BigQuery 保留的時段中執行查詢，提升從記錄檔分析執行的查詢效能。
• 建立快訊政策，監控 SQL 查詢結果。這項功能僅在查詢記錄資料時支援。 詳情請參閱「使用快訊政策監控 SQL 查詢結果」。

本文件不會說明如何建立連結的資料集，這需要特定資料類型的程序。如要瞭解如何建立連結的資料集，請參閱使用連結的資料集查詢記錄檔資料或使用連結的資料集查詢追蹤資料。

事前準備

登入 Google Cloud 帳戶。如果您是 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.

啟用 Observability API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 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，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

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

   • 觀測檢視畫面存取者 (roles/observability.viewAccessor) 在您要查詢的觀測檢視畫面中，這個角色支援 IAM 條件，可讓您將授權限制在特定檢視區塊。如果未在角色授予作業中附加條件，主體就能存取所有可觀測性檢視畫面。可觀測性檢視畫面為公開測試版。
   • 您專案的「Observability Analytics User」 (roles/observability.analyticsUser) 權限。這個角色具備儲存及執行私人查詢，以及執行共用查詢所需的權限。
   • 記錄檢視器 (roles/logging.viewer) 專案
   • 記錄檔檢視存取者 (roles/logging.viewAccessor) 在儲存要查詢記錄檢視的專案中。

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

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

查詢記錄檔和追蹤記錄資料

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

• 載入系統定義的查詢、編輯查詢，然後執行查詢。
• 輸入並執行自訂查詢。舉例來說，您可以貼上或撰寫查詢。自訂查詢可包含聯結、巢狀查詢和其他複雜的 SQL 陳述式。如需範例，請參閱「SQL 查詢範例」。
• 選取選單選項來建構查詢，然後執行該查詢。 記錄檔分析會將您的選取項目轉換為 SQL 查詢，您可查看及編輯查詢。

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

1. 在 Google Cloud 控制台中，前往 「Log Analytics」(記錄檔分析) 頁面：

   前往「Log Analytics」(記錄檔分析)

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

   注意： 如果「Log Analytics」(記錄檔分析) 頁面上的視窗顯示「開始使用 Log Analytics」訊息，請點選視窗上的 「關閉」。

2. 在「資料檢視」選單中選取檢視畫面。

   如要尋找要查詢的檢視畫面，請使用「篩選」列，或捲動清單：

   • 記錄檢視畫面會列在「區隔」記錄專區中，並依值區和檢視畫面 ID 排序。

   • Analytics 資料檢視會列在「data_table」data_table「Analytics Views」部分，並依資料檢視的位置和 ID 排序。可觀測性檢視畫面為公開測試功能，

   • 「追蹤記錄」部分會列出一個追蹤記錄檢視畫面。可觀測性檢視畫面為公開測試版。

     如果沒有名為 _Trace.Spans._AllSpans 的檢視區塊，表示Google Cloud 專案不含名為 _Trace 的可觀測性值區。如要瞭解如何解決這項失敗問題，請參閱「追蹤儲存空間初始化失敗」。

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

   • 如要載入依據「查詢產生器」定義的系統查詢 (可透過選單選項定義查詢)，請確認「查詢」窗格顯示「查詢產生器」。如果系統顯示 SQL 編輯器，請按一下「Builder」。

   • 如要載入擷取 JSON 值的系統定義查詢，請確認「查詢」窗格顯示 SQL 編輯器。如果這個窗格顯示「查詢產生器」，請按一下 「SQL」。

4. 在「結構定義」窗格中選取「查詢」，然後按一下「覆寫」。

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

5. 選用：修改查詢。

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

   Log Analytics 會在表格中顯示查詢結果。不過，您可以建立圖表，也可以將表格或圖表儲存至自訂資訊主頁。詳情請參閱「繪製 SQL 查詢結果圖表」。

   如果工具列顯示「在 BigQuery 中執行」，則必須切換 Log Analytics，使用預設查詢引擎。如要進行這項變更，請在「查詢」窗格的工具列中，按一下「設定」，然後選取「Analytics (預設)」。

輸入並執行自訂查詢

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

1. 在 Google Cloud 控制台中，前往 「Log Analytics」(記錄檔分析) 頁面：

   前往「Log Analytics」(記錄檔分析)

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

   注意： 如果「Log Analytics」(記錄檔分析) 頁面上的視窗顯示「開始使用 Log Analytics」訊息，請點選視窗上的 「關閉」。

2. 在「查詢」窗格中，按一下「SQL」。

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

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

   • 您查詢的檢視畫面會決定 FROM 子句的格式：

     記錄資料

     您可以查詢記錄檢視畫面或數據分析檢視畫面。 請使用下列格式撰寫 FROM 子句：

     • 記錄檢視：

       FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
       

     • Analytics 資料檢視：

       FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`
       

     上述運算式中的欄位具有下列意義：

     • PROJECT_ID：專案的 ID。
     • LOCATION：記錄檢視畫面或分析資料檢視畫面的位置。
     • BUCKET_ID：記錄 bucket 的名稱或 ID。
     • LOG_VIEW_ID：記錄檢視的 ID，最多 100 個字元，只能包含英文字母、數字、底線和連字號。
     • ANALYTICS_VIEW_ID：Analytics 檢視區塊的 ID，最多 100 個字元，只能包含英文字母、數字、底線和連字號。

     如果查詢窗格顯示參照 FROM 陳述式的錯誤訊息，表示系統找不到檢視區塊。如要瞭解如何解決這項失敗問題，請參閱「Error FROM clause must contain exactly one log view」。

     追蹤資料

     預先發布版

     這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

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

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

     上述運算式中的欄位具有下列意義：

     • PROJECT_ID：專案的 ID。
     • LOCATION：可觀測性 bucket 的位置。

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

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

   Log Analytics 會在表格中顯示查詢結果。不過，您可以建立圖表，也可以將表格或圖表儲存至自訂資訊主頁。詳情請參閱「繪製 SQL 查詢結果圖表」。

   如果工具列顯示「在 BigQuery 中執行」，則必須切換 Log Analytics，使用預設查詢引擎。如要進行這項變更，請在「查詢」窗格的工具列中，按一下「設定」，然後選取「Analytics (預設)」。

建立、編輯及執行查詢

您可以在「查詢產生器」介面中，從選單中選取項目來建立查詢。記錄檔分析會將您的選取項目轉換為 SQL 查詢，您可以查看及編輯。舉例來說，您可能會先使用查詢建構工具介面，然後切換至 SQL 編輯器來調整查詢。

記錄檔分析一律可將查詢建立工具介面中的選單選項轉換為 SQL 查詢。不過，並非所有 SQL 查詢都能以查詢建構工具介面表示。舉例來說，這個介面無法表示含有聯結的查詢。

注意： 您想查詢的欄位可能不會列在查詢產生器介面中。如果資料欄的資料類型為 JSON，記錄分析會自動推斷資料欄的欄位。如要讓查詢使用系統未自動推論的 JSON 欄位，請切換至 SQL 編輯器並撰寫查詢。

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

1. 在 Google Cloud 控制台中，前往 「Log Analytics」(記錄檔分析) 頁面：

   前往「Log Analytics」(記錄檔分析)

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

   注意： 如果「Log Analytics」(記錄檔分析) 頁面上的視窗顯示「開始使用 Log Analytics」訊息，請點選視窗上的 「關閉」。

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

3. 使用「來源」選單選取要查詢的檢視畫面。系統會將您的選取項目對應至 SQL 查詢中的 FROM 子句。

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

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

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

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

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

       為避免語法錯誤，您套用至某個資料欄的任何匯總和分組，都會自動套用至其他資料欄。如需如何匯總及分組項目的範例，請參閱使用查詢產生器分組及匯總資料。

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

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

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

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

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

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

   Log Analytics 會在表格中顯示查詢結果。不過，您可以建立圖表，也可以將表格或圖表儲存至自訂資訊主頁。詳情請參閱「繪製 SQL 查詢結果圖表」。

   如果工具列顯示「在 BigQuery 中執行」，則必須切換 Log Analytics，使用預設查詢引擎。如要進行這項變更，請在「查詢」窗格的工具列中，按一下「設定」，然後選取「Analytics (預設)」。

範例：使用查詢產生器分組及匯總資料

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

在「資料欄」元素中選取的每個欄位，都會附上含有下列選項的選單：

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

下圖說明如何建構查詢，將項目分組，然後執行某種匯總作業。

記錄資料

這個範例說明如何使用查詢建構工具，依嚴重程度和時間戳記將記錄項目分組，然後計算每個群組的 http_request.response_size 欄位平均值。

如要建立查詢來分組及彙整資料，請從查詢建立工具選單中選取下列項目：

1. 在「資料欄」選單中，選取「timestamp」、「severity」和「http_request.response_size」欄位。

   1. 如要將資料分組，請按一下 timestamp 欄位，開啟設定對話方塊。在這個對話方塊中，選取「Group by」(分組依據) 選項，並將「Truncation Granularity」(截斷精細度) 設為 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

追蹤資料

預先發布版

這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

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

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

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. 在「Columns」(欄) 元素中，按一下「Add column」(新增欄)。
   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 控制台中，前往 「Log Analytics」(記錄檔分析) 頁面：

   前往「Log Analytics」(記錄檔分析)

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

2. 在「資料檢視」選單中選取檢視畫面。

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

   記錄資料

   記錄檢視畫面會使用固定結構定義，對應於 LogEntry。如果是分析檢視畫面，您可以修改 SQL 查詢來變更結構定義。

   追蹤資料

   預先發布版

   這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

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

   如果沒有名為 _Trace.Spans._AllSpans 的檢視區塊，表示Google Cloud 專案不含名為 _Trace 的可觀測性值區。如要瞭解如何解決這項失敗問題，請參閱「追蹤儲存空間初始化失敗」。

限制

如要查詢多個檢視區塊，這些檢視區塊必須位於相同位置。舉例來說，如果您在 us-east1 位置儲存兩個檢視畫面，一個查詢就能同時查詢這兩個檢視畫面。您也可以查詢儲存在 us 多區域中的兩個檢視區塊。不過，如果檢視畫面的位置是 global，則該檢視畫面可以位於任何實體位置。因此，如果兩個檢視區塊都有 global 的位置，聯結可能會失敗。

如要查看記錄資料適用的限制清單，請參閱「記錄分析：限制」。

後續步驟

• 圖表 SQL 查詢結果。
• 儲存及共用查詢。
• SQL 查詢示例。