SQL 查詢示例

本文包含查詢範例，可用於查詢記錄和追蹤資料。

支援的 SQL 語言

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

透過「記錄檔分析」頁面發出的 SQL 查詢，不支援下列 SQL 指令：

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

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

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)

追蹤資料

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

-- Matches trace spans whose start_time is within the most recent 1 hour.
WHERE start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

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

事前準備

登入 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.

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.

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

如要取得載入「記錄分析」頁面、在追蹤記錄資料上撰寫、執行及儲存私人查詢所需的權限，請要求管理員授予您下列 IAM 角色：
- 觀測檢視畫面存取者 (roles/observability.viewAccessor) 在您要查詢的觀測檢視畫面中，這個角色支援 IAM 條件，可讓您將授權限制在特定檢視區塊。如果未在角色授予作業中附加條件，主體就能存取所有可觀測性檢視畫面。可觀測性檢視畫面為公開測試版。
- 您專案的「Observability Analytics User」 (roles/observability.analyticsUser) 權限。這個角色具備儲存及執行私人查詢，以及執行共用查詢所需的權限。
- 記錄檢視器 (roles/logging.viewer) 專案。
- 記錄檔檢視存取者 (roles/logging.viewAccessor) 在儲存要查詢記錄檢視的專案中。
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

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

在 Google Cloud 控制台中，前往「Log Analytics」(記錄檔分析) 頁面：
前往「Log 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 檢視區的位置和名稱。
追蹤資料

以下顯示查詢 _AllSpans 檢視區塊時，FROM 原因的格式：
```
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
```
FROM 子句包含下列欄位：
- PROJECT_ID：專案的 ID。
- LOCATION：可觀測性 bucket 的位置。
- _Trace 是可觀測性值區的名稱
- Spans 是資料集名稱。
- _AllSpans 是視圖的名稱。
注意： 路徑的分隔符號為半形句號 (.)。如果路徑元素 (例如 Google Cloud 專案) 含有半形句號字元，請務必以單引號反引號 (`) 包住每個路徑欄位。

如要在 BigQuery Studio 頁面使用本文顯示的查詢，或使用 bq 指令列工具，請編輯 FROM 子句，然後輸入連結資料集的路徑。

記錄資料

舉例來說，如要查詢專案 myproject 中名為 mydataset 的連結資料集上的檢視區塊，路徑為 myproject.mydataset._AllLogs。_AllLogs

追蹤資料

舉例來說，如要查詢專案 myproject 中名為 my_linked_dataset 的連結資料集上的 _AllSpans 檢視區塊，路徑為 `myproject.my_linked_dataset._AllSpans`。

常見用途

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

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

如要查詢 _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 函式可提高查詢效率。

顯示所有追蹤記錄資料

如要查詢 _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 個百分位數的 span 延遲時間

如要顯示每個 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 欄位的平均值。

篩選記錄項目

如要對查詢套用篩選器，請新增 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 exits.
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)

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

依資源篩選

如要依資源篩選記錄和追蹤資料，請在 WHERE 子句中新增 resource.type 陳述式：

-- 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 子句只會比對第二個記錄項目。

篩選追蹤記錄項目

如要對查詢套用篩選器，請新增 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 是整數，可接受介於零到五之間的值：

如要只分析指定 kind 的範圍，請使用下列子句：

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

如要分析 kind 值為一或二的範圍，請使用下列子句：

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

依 RECORD 資料類型篩選

追蹤記錄架構中的部分欄位資料類型為 RECORD。這些欄位可以儲存一或多個資料結構，也可以儲存相同資料結構的重複項目。

依狀態或狀態代碼篩選

status 欄位是資料類型為 RECORD 的欄位範例。這個欄位會儲存一個資料結構，成員標示為 code 和 message。

如要只在 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 資料類型儲存，但這些是重複欄位。

如要比對至少有一個事件的範圍，請使用下列子句：

-- 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。每個屬性都是鍵/值組合。

如要只分析指定 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 子句的所有資料列視為一個群組。

每個 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說明文件。

將追蹤記錄資料分組及匯總

本節說明如何分組及彙整範圍。如果您未指定分組，但指定了匯總，則系統會列印一個結果，因為 SQL 會將滿足 WHERE 子句的所有項目視為一個群組。

每個 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 說明文件和日期時間函式。

依狀態碼計算範圍數量

如要顯示具有特定狀態碼的範圍數量，請執行下列查詢：

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，查詢結果會列出每個跨度名稱的項目數量。

計算所有範圍的平均時間長度

如要顯示平均時間長度，請依 span 名稱分組 span 資料，然後執行下列查詢：

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

跨欄搜尋

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

以權杖為準的搜尋：指定搜尋位置和搜尋查詢，然後使用 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」、「193」、「12」和「15」：

  SEARCH(t,"35.193.12.15")

先前的 SEARCH 陳述式會在單一欄位符合所有四個符記時，比對資料列。權杖的順序沒有影響。

您可以在查詢中加入多個 SEARCH 陳述式。舉例來說，在先前的查詢中，您可以將記錄 ID 的篩選條件替換為下列陳述式：

  SEARCH(t,"`cloudaudit.googleapis.com/data_access`")

先前的陳述式會搜尋記錄檢視畫面中記錄項目的每個欄位，而原始陳述式只會搜尋記錄項目的 log_id 欄位。

如要對多個欄位執行多項搜尋，請以半形空格分隔個別字串。舉例來說，下列陳述式會比對欄位包含「Hello World」、「happy」和「days」的資料列：

  SEARCH(t,"`Hello World` happy days")

最後，您可以搜尋特定欄位，不必搜尋整個表格。舉例來說，下列陳述式只會搜尋名為 text_payload 和 json_payload 的資料欄：

   SEARCH((text_payload, json_payload) ,"`35.222.132.245`")

如要瞭解 SEARCH 函式的參數處理方式，請參閱 BigQuery 參考頁面「搜尋函式」。

在記錄檢視中搜尋子字串

舉例來說，下列查詢會擷取所有具有特定 IP 位址的資料存取稽核記錄項目，且這些項目的時間戳記位於特定時間範圍內。最後，查詢會排序結果，然後顯示最舊的 20 個結果：

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.
  -- CONTAINS_SUBSTR performs a contains-test.
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  CONTAINS_SUBSTR(t,"35.193.12.15")
ORDER BY timestamp ASC
LIMIT 20

查詢多個檢視區塊

查詢陳述式可掃描一或多個資料表或運算式，然後傳回運算的結果資料列。舉例來說，您可以使用查詢陳述式，以各種方式合併不同資料表或資料集中的 SELECT 陳述式結果，然後從合併的資料中選取資料欄。

如要聯結檢視區塊，請遵守下列限制：

檢視區塊的位置符合下列其中一項條件：
- 所有檢視區都有相同的位置。
- 所有檢視畫面都位於 global 或 us 位置。
如果儲存空間資源使用客戶自行管理的加密金鑰 (CMEK)，則必須符合下列其中一項條件：
- 使用 CMEK 的儲存空間資源會使用相同的 Cloud KMS 金鑰。
- 使用 CMEK 的儲存空間資源具有共同祖先，而該祖先會指定與儲存空間資源位於相同位置的預設 Cloud KMS 金鑰。
當一或多個儲存空間資源使用 CMEK 時，系統會使用通用 Cloud KMS 金鑰或上層的預設 Cloud KMS 金鑰，加密聯結產生的暫時資料。

舉例來說，假設您有兩個位於相同位置的檢視區塊。接著，在符合下列任一條件時，即可聯結這些檢視畫面：

儲存空間資源不會使用 CMEK。
一個儲存空間資源使用 CMEK，另一個則否。
兩個儲存空間資源都使用 CMEK，且都使用相同的 Cloud KMS 金鑰。
這兩種儲存空間資源都使用 CMEK，但使用的金鑰不同。不過，這些資源共用一個祖先，該祖先會指定與儲存空間資源位於相同位置的預設 Cloud KMS 金鑰。

舉例來說，假設記錄 bucket 和可觀測性 bucket 的資源階層包含同一個機構。如果已為機構設定 Cloud Logging 的預設資源設定，並為可觀測性 bucket 設定儲存位置的預設 Cloud KMS 金鑰，即可加入這些 bucket 的檢視畫面。

依追蹤記錄 ID 彙整兩個記錄檢視畫面

如要合併兩個資料表的資訊，請使用其中一個 join 運算子：

SELECT
  -- Do an inner join on two tables by using the span ID and trace ID.
  -- Don't join only by span ID, as this field isn't globally unique.
  -- From the first view, show the timestamp, severity, and JSON payload.
  -- From the second view, show the JSON payload.
  a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_1` a
JOIN  `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_2` b
ON
  a.span_id = b.span_id AND
  a.trace = b.trace
LIMIT 100

使用聯集陳述式查詢兩個記錄檢視區塊

如要合併兩個以上的 SELECT 陳述式結果並捨棄重複資料列，請使用 UNION 運算子。如要保留重複的資料列，請使用 UNION ALL 運算子：

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
-- Create a union of two log views
FROM(
  SELECT * FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_1`
  UNION ALL
  SELECT * FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_2`
)
-- Sort the union by timestamp.
ORDER BY timestamp ASC
LIMIT 100

使用追蹤記錄 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，以收集更多資訊。此外，結果也會列出記錄項目的嚴重程度和 JSON 酬載。

移除重複的記錄項目

記錄檔分析不會在執行查詢前移除重複的記錄項目。使用記錄檔瀏覽器查詢記錄項目時，系統會比較記錄名稱、時間戳記和插入 ID 欄位，並移除重複項目，這與上述行為不同。

您可以使用資料列層級驗證來移除重複的記錄項目。

詳情請參閱「疑難排解：記錄檔分析結果中出現重複的記錄項目」。

後續步驟

如需 SQL 參考說明文件或其他範例，請參閱下列文件：

SQL 查詢示例 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

支援的 SQL 語言

最佳做法

記錄資料

追蹤資料

事前準備

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

記錄資料

追蹤資料

記錄資料

追蹤資料

常見用途

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

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

顯示所有追蹤記錄資料

顯示常見範圍資訊

顯示第 50 和第 99 個百分位數的 span 延遲時間

篩選記錄項目

依酬載類型篩選記錄項目

依時間戳記篩選記錄資料

依資源篩選

依嚴重程度篩選

依記錄檔名稱篩選

依資源標籤篩選記錄項目

依 HTTP 要求篩選

依 HTTP 狀態篩選

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

篩選追蹤記錄項目

依字串資料類型篩選

依整數資料類型篩選

依 RECORD 資料類型篩選

依狀態或狀態代碼篩選

依事件或連結篩選

依 JSON 資料類型篩選

將記錄項目分組及匯總

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

依資源將記錄項目分組

依嚴重性將記錄項目分組

依據記錄項目的 log_id 分組

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

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

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

將追蹤記錄資料分組及匯總

依開始時間將範圍分組

依狀態碼計算範圍數量

計算所有範圍的平均時間長度

計算每個服務名稱的平均時間和百分位數

跨欄搜尋

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

在記錄檢視中搜尋子字串

查詢多個檢視區塊

依追蹤記錄 ID 彙整兩個記錄檢視畫面

使用聯集陳述式查詢兩個記錄檢視區塊

使用追蹤記錄 ID 彙整追蹤記錄和記錄資料

移除重複的記錄項目

後續步驟

SQL 查詢示例

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