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

SQL 查詢示例

本文提供範例查詢，說明如何查詢已升級為使用 Observability Analytics 的記錄檔 bucket 中儲存的記錄項目。您可以在 Google Cloud 控制台的「Observability Analytics」(觀測能力分析) 頁面，對這些值區執行 SQL 查詢。如需更多範例，請參閱 logging-analytics-samples 和 security-analytics GitHub 存放區。

本文不會說明 SQL，也不會介紹如何傳送及儲存記錄檔項目。如要瞭解這些主題，請參閱「後續步驟」一節。

本頁面的範例會查詢記錄檢視。如要查詢數據分析檢視區塊，請使用下列路徑格式： `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`。在上述運算式中，PROJECT_ID 是專案的 ID，LOCATION 和 ANALYTICS_VIEW_ID 則是 Analytics 檢視區的位置和名稱。

支援的 SQL 語言

「Observability Analytics」頁面中使用的查詢支援 GoogleSQL 函式，但有部分例外情況。

透過「Observability Analytics」頁面發出的 SQL 查詢，不支援下列 SQL 指令：

DDL 和 DML 指令
JavaScript 使用者定義函式
BigQuery ML 函式
SQL 變數

只有在透過 BigQuery Studio 和 Looker Studio 頁面，或使用 bq 指令列工具查詢連結的 BigQuery 資料集時，才支援下列項目：

JavaScript 使用者定義函式
BigQuery ML 函式
SQL 變數

最佳做法

如要設定查詢的時間範圍，建議使用時間範圍選取器。舉例來說，如要查看過去一週的資料，請從時間範圍選取器選取「過去 7 天」。你也可以使用時間範圍選取器指定開始和結束時間、指定要查看的時間，以及變更時區。

如果在 WHERE 子句中加入 timestamp 欄位，系統就不會使用時間範圍選取器設定。以下範例說明如何依時間戳記篩選：

-- Matches log entries whose timestamp is within the most recent 1 hour.
WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

如要進一步瞭解如何依時間篩選，請參閱「時間函式」和「時間戳記函式」。

事前準備

本節說明使用可觀測性分析前必須完成的步驟。

設定記錄檔 bucket

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

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

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
針對每個含有要查詢記錄檢視的記錄檔 bucket，請確認「可使用觀測能力分析」欄顯示「開啟」。如果顯示「升級」，請按一下「升級」並完成對話方塊。

設定 IAM 角色和權限

本節說明使用可觀測性分析所需的 IAM 角色或權限：

如要取得使用可觀測性分析和查詢記錄檔檢視畫面所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- 如要查詢 _Required 和 _Default 記錄檔值區，請使用記錄檢視器 (roles/logging.viewer)：
- 如要查詢專案中的所有記錄檢視畫面：記錄檢視存取者 (roles/logging.viewAccessor)
如要將主體限制為特定記錄檢視畫面，請在專案層級授予記錄檢視畫面存取者角色時新增 IAM 條件，或在記錄檢視畫面的政策檔案中新增 IAM 繫結。詳情請參閱「控管記錄檢視畫面的存取權」。

您必須具備這些權限，才能在「記錄探索器」頁面查看記錄項目。如要瞭解查詢使用者定義 bucket 中的檢視區塊，或查詢 _Default 記錄檔 bucket 的 _AllLogs 檢視區塊時，需要哪些額外角色，請參閱「Cloud Logging 角色」。
如要取得查詢 Analytics 檢視畫面所需的權限，請要求管理員授予您專案的「可觀測性 Analytics 使用者」(roles/observability.analyticsUser) IAM 角色。

如何使用這個頁面上的查詢

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

如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。
在「查詢」窗格中，按一下「SQL」，然後複製查詢並貼到 SQL 查詢窗格。

複製查詢前，請在 FROM 子句中，替換下列欄位
- PROJECT_ID：專案的 ID。
- LOCATION：記錄檢視畫面或分析資料檢視畫面的位置。
- BUCKET_ID：記錄檔 bucket 的名稱或 ID。
- LOG_VIEW_ID：記錄檢視的 ID，最多 100 個字元，只能包含英文字母、數字、底線和連字號。
以下顯示記錄檢視畫面的 FROM 子句格式：
```
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
```
本頁面的記錄範例會查詢記錄檢視。如要查詢數據分析檢視區塊，請使用下列路徑格式：`analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`。在上述運算式中，PROJECT_ID 是專案的 ID，LOCATION 和 ANALYTICS_VIEW_ID 則是 Analytics 資料檢視的所在位置和名稱。

注意： 路徑的分隔符號為半形句號 (.)。如果路徑元素 (例如 Google Cloud 專案) 含有半形句號字元，請務必以單一反引號 (`) 包住每個路徑欄位。

如要在 BigQuery Studio 頁面使用本文顯示的查詢，或使用 bq 指令列工具，請編輯 FROM 子句，然後輸入連結的 BigQuery 資料集路徑。舉例來說，如要查詢專案 myproject 中名為 mydataset 的連結 BigQuery 資料集上的 _AllLogs 檢視區塊，路徑為 myproject.mydataset._AllLogs。

常見用途

本節列出幾個常見用途，協助您建立自訂查詢。

在預設記錄值區中顯示記錄項目

如要查詢 _Default bucket，請執行下列查詢：

SELECT
  timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload
FROM
  `PROJECT_ID.LOCATION._Default._AllLogs`
-- Limit to 1000 entries
LIMIT 1000

使用規則運算式擷取欄位值

如要使用規則運算式從字串中擷取值，請使用 REGEXP_EXTRACT 函式：

SELECT
  -- Display the timestamp, and the part of the name that begins with test.
  timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Get the value of jobName, which is a subfield in a JSON structure.
  JSON_VALUE(json_payload.jobName) IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20

詳情請參閱 REGEXP_EXTRACT說明文件。

如要比對子字串 (如先前的查詢)，使用 CONTAINS_SUBSTR 函式可提高查詢效率。

篩選記錄項目

如要對查詢套用篩選器，請新增 WHERE 子句。這個子句中使用的語法取決於欄位的資料類型。本節提供幾種不同資料類型的範例。

依據酬載類型篩選記錄項目

記錄項目可採用下列三種輸出內容類型之一。如要依酬載類型篩選記錄項目，請使用下列其中一個子句：

文字酬載

-- Matches log entries that have a text payload.
WHERE text_payload IS NOT NULL

JSON 酬載

-- Matches log entries that have a JSON payload.
WHERE json_payload IS NOT NULL

Proto 酬載

-- Matches log entries that have a proto payload.
-- Because proto_payload has a data type of RECORD, this statement tests
-- whether a mandatory subfield exists.
WHERE proto_payload.type IS NOT NULL

在查詢結果中，json_payload 和 proto_payload 欄位都會以 JSON 格式呈現，您可以瀏覽這些欄位。

依時間戳記篩選記錄資料

如要依時間戳記篩選記錄項目，建議使用時間範圍選取器。不過，您也可以在 WHERE 子句中指定 timestamp：

-- Matches log entries whose timestamp is within the most recent hour
WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

如要進一步瞭解如何依時間篩選，請參閱「時間函式」和「時間戳記函式」。

依資源篩選

如要依資源篩選記錄資料，請將 resource.type 陳述式新增至 WHERE 子句：

-- Matches log entries whose resource type is gce_instance
WHERE resource.type = "gce_instance"

依據嚴重性篩選

如要依嚴重性篩選記錄資料，請在 WHERE 子句中新增 severity 陳述式：

-- Matches log entries whose severity is INFO or ERROR
WHERE severity IS NOT NULL AND severity IN ('INFO', 'ERROR')

您也可以依 severity_number (整數) 篩選記錄項目。舉例來說，下列子句會比對嚴重性等級至少為 NOTICE 的所有記錄項目：

-- Matches log entries whose severity level is at least NOTICE
WHERE severity_number IS NOT NULL AND severity_number > 200

如要瞭解列舉值，請參閱 LogSeverity。

依記錄檔名稱篩選

如要依記錄檔名稱篩選記錄檔資料，請將 log_name 或 log_id 陳述式新增至 WHERE 子句：

記錄名稱會指定資源路徑：

-- Matches log entries that have the following log ID.
WHERE log_name="projects/cloud-logs-test-project/logs/cloudaudit.googleapis.com%2Factivity"

記錄 ID 會省略資源路徑：

-- Matches log entries that have the following log id.
WHERE log_id = "cloudaudit.googleapis.com/data_access"

依資源標籤篩選記錄項目

資源標籤會儲存為 JSON 結構。如要依據 JSON 結構中的欄位值篩選，請使用 JSON_VALUE 函式：

SELECT
  timestamp, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries whose resource type is gce_instance and whose zone is
  -- us-central1-f. Because resource has data type JSON, you must use JSON_VALUE
  -- to get the value for subfields, like zone.
  resource.type = "gce_instance" AND
  JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC

先前的查詢依賴資源標籤的格式，因為這些標籤會儲存在記錄項目中。以下是資源欄位的範例：

{
   type: "gce_instance"
   labels: {
      instance_id: "1234512345123451"
      project_id: "my-project"
      zone: "us-central1-f"
   }
}

如要瞭解所有可擷取及轉換 JSON 資料的函式，請參閱 JSON 函式。

依 HTTP 要求篩選

如要只查詢含有 HTTP 要求欄位的記錄項目，請使用下列子句：

-- Matches log entries that have a HTTP request_method field.
-- Don't compare http_request to NULL. This field has a data type of RECORD.
WHERE http_request.request_method IS NOT NULL

您也可以使用 IN 陳述式：

-- Matches log entries whose HTTP request_method is GET or POST.
WHERE http_request.request_method IN ('GET', 'POST')

依 HTTP 狀態篩選

如要只查詢具有 HTTP 狀態的記錄項目，請使用下列子句：

-- Matches log entries that have an http_request.status field.
WHERE http_request.status IS NOT NULL

依 JSON 資料類型中的欄位篩選

如要只在 JSON 資料類型欄位的子欄位具有特定值時查詢記錄項目，請使用 JSON_VALUE 函式擷取值：

-- Compare the value of the status field to NULL.
WHERE JSON_VALUE(json_payload.status) IS NOT NULL

前一個子句與下列子句略有不同：

-- Compare the status field to NULL.
WHERE json_payload.status IS NOT NULL

第一個子句會測試狀態欄位的值是否為 NULL。第二個子句會測試狀態欄位是否存在。假設記錄檢視包含兩個記錄項目。在一個記錄項目中，json_payload 欄位採用下列格式：

{
    status: {
        measureTime: "1661517845"
    }
}

另一個記錄項目的 json_payload 欄位結構不同：

{
    @type: "type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished"
    jobName: "projects/my-project/locations/us-central1/jobs/test1"
    relativeUrl: "/food=cake"
    status: "NOT_FOUND"
    targetType: "APP_ENGINE_HTTP"
}

子句 WHERE json_payload.status IS NOT NULL 會比對兩個記錄項目。不過，子句 WHERE JSON_VALUE(json_payload.status) IS NOT NULL 只會比對第二個記錄項目。

將記錄項目分組及匯總

本節以先前的範例為基礎，說明如何將記錄項目分組及彙整。如果您未指定分組，但指定了匯總，則會列印一個結果，因為 SQL 會將滿足 WHERE 子句的所有資料列視為一個群組。

每個 SELECT 運算式都必須包含在群組欄位中，或經過匯總。

依時間戳記將記錄項目分組

如要依時間戳記分組資料，請使用 TIMESTAMP_TRUNC 函式，將時間戳記截斷為指定精細度 (如 HOUR)：

SELECT
  -- Truncate the timestamp by hour.
  TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
  JSON_VALUE(json_payload.status) AS status,
  -- Count the number log entries in each group.
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries that have a status field whose value isn't NULL.
  json_payload IS NOT NULL AND JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY
  -- Group by hour and status
  hour,status
ORDER BY hour ASC

詳情請參閱 TIMESTAMP_TRUNC 說明文件和日期時間函式。

依資源將記錄項目分組

下列查詢說明如何依資源類型將記錄項目分組，然後計算每個群組中的記錄項目數：

SELECT
   -- Count the number of log entries for each resource type
   resource.type, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
GROUP BY resource.type
LIMIT 100

依嚴重性將記錄項目分組

下列查詢說明如何依嚴重性將記錄項目分組，然後計算每個群組中的記錄項目數：

SELECT
  -- Count the number of log entries for each severity.
  severity, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100

依據 `log_id` 將記錄項目分組

下列查詢說明如何依記錄 ID 將記錄項目分組，然後計算每個群組中的記錄項目數：

SELECT
  -- Count the number of log entries for each log ID.
  log_id, COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100

計算每個網址的平均 HTTP 要求延遲時間

下列查詢說明如何依 HTTP 要求網址和位置將記錄項目分組，然後計算每個群組中的記錄項目數：

SELECT
  -- Compute the average latency for each group. Because the labels field has a
  -- data type of JSON, use JSON_VALUE to get the value of checker_location.
  JSON_VALUE(labels.checker_location) AS location,
  AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  -- Matches log entries when the request_method field is GET.
  http_request IS NOT NULL AND http_request.request_method IN ('GET')
GROUP BY
  -- Group by request URL and location
  http_request.request_url, location
ORDER BY location
LIMIT 100

計算子網路測試的平均傳送位元組數

下列查詢說明如何依資源標籤中指定的位置將記錄項目分組，然後計算每個群組中的記錄項目數：

SELECT
  -- Compute the average number of bytes sent per location. Because labels has
  -- a data type of JSON, use JSON_VALUE to get the value of the location field.
  -- bytes_sent is a string. Must cast to a FLOAT64 before computing average.
  JSON_VALUE(resource.labels.location) AS location,
  AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  resource.type = "gce_subnetwork" AND json_payload IS NOT NULL
GROUP BY
  -- Group by location
  location
LIMIT 100

詳情請參閱 JSON 函式和轉換函式。

計算欄位符合模式的記錄項目

如要傳回與規則運算式相符的子字串，請使用 REGEXP_EXTRACT 函式：

SELECT
  -- Extract the value that begins with test.
  -- Count the number of log entries for each name.
  REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
WHERE
  json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20

如需其他範例，請參閱REGEXP_EXTRACT說明文件。

跨欄搜尋

本節說明兩種方法，可用於搜尋所查詢檢視區塊的多個資料欄：

以權杖為準的搜尋：指定搜尋位置和搜尋查詢，然後使用 SEARCH 函式。由於 SEARCH 函式有特定的資料搜尋規則，建議您參閱 SEARCH 說明文件。
以子字串為基礎的搜尋：您提供搜尋位置、字串常值，然後使用 CONTAINS_SUBSTR 函式。系統會執行不區分大小寫的測試，判斷運算式中是否存在字串常值。如果字串常值存在，CONTAINS_SUBSTR 函式會傳回 TRUE，否則會傳回 FALSE。搜尋值必須是 STRING 常值，但不得為 NULL 常值。

在記錄檢視畫面中依權杖搜尋

下列查詢只會保留欄位與「35.193.12.15」完全相符的資料列：

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID` AS t
WHERE
  -- Search data access audit logs for the IP address that matches 35.193.12.15.
  -- The use of backticks prevents the string from being tokenized.
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  SEARCH(t,"`35.193.12.15`")
ORDER BY timestamp ASC
LIMIT 20

如果查詢字串中省略反引號，系統會根據SEARCH說明文件中定義的規則分割查詢字串。舉例來說，執行下列陳述式時，查詢字串會分割為四個權杖：「35」、「19