Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Observability Analytics 查詢及分析記錄

本文說明如何使用 Observability Analytics 查詢及分析記錄資料，這項工具提供 SQL 查詢介面。您可以使用 SQL 執行計算欄位符合特定模式的記錄項目數量等工作。Observability Analytics 提供 SQL 編輯器和選單式系統，可用於建構查詢。如要查看查詢結果，您可以使用表格形式，也可以將資料以圖表形式呈現。您可以將圖表儲存至自訂資訊主頁。

您可以查詢記錄檔 bucket 的記錄檔檢視表或分析檢視表。查詢記錄檢視表時，結構定義會對應至 LogEntry 資料結構。分析檢視表的結構定義是由建立者決定，因此分析檢視表的一種用途，是將記錄資料從 LogEntry 格式轉換為更適合您的格式。

您也可以使用 Observability Analytics 查詢追蹤記錄資料。詳情請參閱「查詢及分析追蹤記錄」。

Observability Analytics 不會簡化記錄項目，這可能會影響查詢的編寫方式。此外，使用 Observability Analytics 時有一些限制。如要進一步瞭解這些主題，請參閱下列文件：

關於連結的 BigQuery 資料集

如要查詢記錄資料，或查詢記錄和追蹤資料，則不需要連結 BigQuery 資料集。在這些情況下，您可以使用「Observability Analytics」頁面。您也可以儲存及分享查詢，並將查詢儲存至自訂資訊主頁。如要瞭解如何查詢追蹤記錄資料，請參閱「查詢及分析追蹤記錄」。

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

將記錄項目資料與其他 BigQuery 資料集彙整。
從其他服務 (例如 BigQuery Studio 頁面或數據分析) 查詢記錄資料。
使用隨選運算單元或 BigQuery 預留運算單元，在 BigQuery 引擎上透過Observability Analytics執行查詢。
建立警告政策，監控 SQL 查詢結果。詳情請參閱「使用警告政策監控 SQL 查詢結果」。

如果您選擇在記錄檔 bucket 上建立連結的 BigQuery 資料集，則會擴大記錄檔資料的安全邊界，納入 BigQuery 服務。也就是說，BigQuery 服務現在可以向連結的 BigQuery 資料集發出查詢，藉此查詢記錄資料。建立連結的 BigQuery 資料集前，建議您先參閱「Observability Analytics 的資料安全性」一文。

事前準備

本節說明使用 Observability Analytics 前必須完成的步驟。

設定記錄檔 bucket

確認記錄檔 bucket 已升級為使用 Observability Analytics：

在 Google Cloud 控制台中，前往「Logs Storage」(記錄檔儲存空間) 頁面：
前往「Logs Storage」(記錄檔儲存空間)

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
針對要查詢記錄檔檢視畫面的每個記錄檔 bucket，確認「可使用 Observability Analytics」欄顯示「開啟」。如果畫面上顯示「Upgrade」(升級)，請按一下「Upgrade」(升級)，然後完成對話方塊。

設定 IAM 角色和權限

本節說明使用 Observability Analytics 所需的 IAM 角色或權限：

如要取得使用 Observability Analytics 和查詢記錄檔檢視表所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- 如要查詢 _Required 和 _Default 記錄檔 bucket，請按照下列步驟操作：記錄檢視器 (roles/logging.viewer)
- 如要查詢專案中的所有記錄檢視表：記錄檢視存取者 (roles/logging.viewAccessor)
如要限制主體只能存取特定記錄檢視，您可以在專案層級授予「記錄檢視存取子」角色時，新增 IAM 條件，或是在記錄檢視的政策檔案中新增 IAM 繫結。詳情請參閱「控管記錄檔檢視畫面的存取權」。

這些權限與在「Logs Explorer」頁面查看記錄項目所需的權限相同。如要瞭解查詢使用者定義 bucket 上的檢視表，或查詢 _Default 記錄檔 bucket 的 _AllLogs 檢視表時，需要哪些其他角色，請參閱「Cloud Logging 角色」。
如要取得查詢分析檢視表所需的權限，請要求管理員授予您專案的 Observability Analytics 使用者 (roles/observability.analyticsUser) IAM 角色。

查詢記錄檔資料

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

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

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

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

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

注意：如果「Observability Analytics」頁面顯示「開始使用 Observability Analytics」訊息，請點選視窗中的「關閉」圖示。
在「Views」(檢視表) 選單中，前往「Logs」(記錄檔) 或「Analytics Views」(分析檢視表) 區段，然後選取要查詢的檢視表。

如要找出要查詢的檢視表，請使用「Filter」(篩選器) 列，或捲動清單：
- 記錄檢視會依 BUCKET_ID.LOG_VIEW_ID 列出，其中這些欄位是指記錄檔 bucket 和記錄檢視的 ID。
- 分析檢視表會依 LOCATION.ANALYTICS_VIEW_ID 列出，其中這些欄位是指分析檢視表的位置和 ID。分析檢視表目前為公開預先發布版。
執行下列其中一個步驟：
- 如要載入依賴「查詢建立工具」的系統定義查詢，請確認「查詢」窗格顯示「查詢建立工具」，以便透過選單選項定義查詢。如果顯示 SQL 編輯器，請按一下「Builder」(建立工具)。
- 如要載入系統定義的查詢來擷取 JSON 值，請確認「Query」(查詢) 窗格顯示 SQL 編輯器。如果這個窗格顯示「Query Builder」(查詢建立工具)，請按一下「SQL」。
在「結構定義」窗格中，依序選取「查詢」和「覆寫」。

「Query」(查詢) 窗格會顯示系統定義的查詢。如果您選取「Query Builder」(查詢建立工具) 模式，但想查看 SQL 查詢，請按一下「SQL」。
選用：修改查詢。
如要執行查詢，請前往工具列並選取「Run Query」(執行查詢)。

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

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

輸入並執行自訂查詢

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

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

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

注意：如果「Observability Analytics」頁面顯示「開始使用 Observability Analytics」訊息，請點選視窗中的「關閉」圖示。
在「查詢」窗格中，點選「SQL」。
- 如要指定日期範圍，建議您使用日期範圍選取器。如果新增指定 timestamp 欄位的 WHERE 子句，該值會覆寫日期範圍選取器中的設定，且該選取器會停用。
- 如需範例，請參閱「SQL 查詢範例」。
- 您可以查詢記錄檢視表或分析檢視表。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：分析檢視表的 ID，長度上限為 100 個字元，且只能包含英文字母、數字、底線和連字號。
  如果查詢窗格顯示參照 FROM 陳述式的錯誤訊息，表示找不到檢視表。如要瞭解如何解決這項失敗問題，請參閱「錯誤：FROM 子句只能含有一個記錄檢視表」。
如要執行查詢，請前往工具列並選取「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 查詢都能透過查詢建立工具介面表示。例如，這個介面無法表示含有彙整的查詢。

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

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

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

注意：如果「Observability Analytics」頁面顯示「開始使用 Observability Analytics」訊息，請點選視窗中的「關閉」圖示。
如果「Query」(查詢) 窗格顯示 SQL 編輯器，請選取「Builder」(建構工具)，開啟「Query Builder」(查詢建立工具) 窗格。
使用「Source」(來源) 選單選取要查詢的檢視表。您選取的項目會對應至 SQL 查詢中的 FROM 子句。
選用：使用下列選單限制或設定結果表格的格式：
- 搜尋所有欄位：搜尋相符的字串。所選項目會對應至 SQL 查詢中的 WHERE 子句。
- 資料欄：選取結果表格中顯示的資料欄。您選取的項目會對應至 SQL 查詢中的 SELECT 子句。
  
  在這個選單中選取欄位名稱後，系統會開啟對話方塊。在這個對話方塊中，您可以執行下列操作：
  - 使用選單匯總或分組資料。
    
    為避免語法錯誤，您對某個資料欄套用的任何匯總和分組，也會自動套用至其他資料欄。如需匯總及分組項目的範例，請參閱「使用查詢建立工具分組及匯總資料」。
  - 將任何類型的值轉換為其他指定的資料類型。詳情請參閱 CAST 說明文件。
  - 使用規則運算式擷取值的子字串。詳情請參閱 REGEXP_EXTRACT 說明文件。
- 篩選器：如要將查詢限制在包含特定屬性或 Span ID 的 Span，請新增篩選器。選單會列出所有可用的篩選條件選項。所選項目會對應至 SQL 查詢中的 WHERE 子句。
- 排序依據：設定要排序的資料欄，以及排序方式為遞增或遞減。所選項目會對應至 SQL 查詢中的 ORDER BY 子句。
- 限制：設定結果表格中的資料列數量上限。您選取的項目會對應至 SQL 查詢中的 LIMIT 子句。
如要執行查詢，請前往工具列並選取「Run Query」(執行查詢)。

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

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

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

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

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

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

以下範例說明如何使用查詢建立工具，依嚴重性和時間戳記將記錄項目分組，然後計算各組 http_request.response_size 欄位的平均值：

在「Columns」(資料欄) 選單中，選取 timestamp、severity 和 http_request.response_size 欄位。
1. 如要將資料分組，請按一下「timestamp」欄位，開啟設定對話方塊。在這個對話方塊中，選取「Group by」(分組依據) 選項，並將「Truncation Granularity」(截斷精細度) 設為 HOUR。系統會自動將分組套用至所有其他欄位，避免發生語法錯誤。如果無效欄位無法套用分組，系統會顯示錯誤訊息。請從選單中移除無效欄位，即可解決這項錯誤。
2. 如要對 http_request.response_size 欄位執行匯總，請按一下該欄位，開啟設定對話方塊。在這個對話方塊中，選取「Aggregate」(匯總)。在「匯總」選單中，按一下「平均值」。
  
  注意：選取「Aggregate」(匯總) 選項後，系統也會自動將分組套用至資料欄。
在「Filters」(篩選器) 選單中，新增 http_request.response_size 並將比較子設為 IS NOT NULL。這個篩選器會比對含有 response_size 值的記錄項目。

查詢建立工具選單應如下所示：

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

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

+-----------------------------------+----------+---------------+
| 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

顯示結構定義

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

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

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

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
在「Views」(檢視表) 選單中，前往「Logs」(記錄檔) 或「Analytics Views」(分析檢視表) 區段，然後選取要查詢的檢視表。

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

記錄檢視畫面的結構定義是固定的，且對應至 LogEntry。如要變更分析檢視表的結構定義，可以修改 SQL 查詢。