本文件說明如何找出從 Cloud Logging 轉送至 BigQuery 資料表的記錄項目。記錄匯出會以小批次將記錄資料串流至 BigQuery，讓您不必執行載入工作即可查詢資料。為協助您建立查詢並瞭解 BigQuery 表格的格式，本文件也說明瞭路由記錄的 BigQuery 結構定義。
Cloud Logging 會使用舊版串流 API，將記錄項目串流至 BigQuery。通常，記錄項目會在 1 分鐘內顯示在 BigQuery 中。不過，建立新資料表時，可能需要幾分鐘的時間才能取得第一筆記錄項目。
事前準備
如要進一步瞭解接收端的概念，請參閱「轉送和儲存空間模式總覽：接收端」。
如需轉送記錄檔的操作說明，請參閱「將記錄檔轉送至支援的目的地」。
如要瞭解如何命名已轉送的記錄項目欄位，請參閱專用於已轉送記錄的 BigQuery 結構定義。
查看記錄
如要查看已路由至 BigQuery 的記錄檔，請執行下列操作：
-
前往 Google Cloud 控制台的「BigQuery」BigQuery頁面：
您也可以透過搜尋列找到這個頁面。
在「Explorer」面板中展開專案並選取資料集。
您可以在「Details」(詳細資料) 分頁中看到記錄項目，也可以查詢資料表以傳回資料。
查詢範例
如要瞭解 BigQuery 查詢語法，請參閱查詢參考資料。資料表萬用字元函式與Flatten 運算子特別實用，前者可讓您跨多個資料表進行查詢，後者允許顯示來自重複欄位的資料。
Compute Engine 查詢範例
下列 BigQuery 查詢會擷取多天與多種記錄類型的記錄項目：
查詢會搜尋前三天的記錄
syslog和apache-access。查詢日期為 2020 年 2 月 23 日，涵蓋 2 月 21 日與 2 月 22 日收到的所有記錄項目，以及在 2 月 23 日發出查詢之前收到的記錄項目。查詢會針對單一 Compute Engine 執行個體
1554300700000000000擷取結果。
SELECT timestamp AS Time, logName as Log, textPayload AS Message FROM (TABLE_DATE_RANGE(my_bq_dataset.syslog_, DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())), (TABLE_DATE_RANGE(my_bq_dataset.apache_access_, DATE_ADD(CURRENT_TIMESTAMP(), -2, 'DAY'), CURRENT_TIMESTAMP())) WHERE resource.type == 'gce_instance' AND resource.labels.instance_id == '1554300700000000000' ORDER BY time;
下面是一些範例輸出列：
Row | Time | Log | Message --- | ----------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- 5 | 2020-02-21 03:40:14 UTC | projects/project-id/logs/syslog | Feb 21 03:40:14 my-gce-instance collectd[24281]: uc_update: Value too old: name = 15543007601548826368/df-tmpfs/df_complex-used; value time = 1424490014.269; last cache update = 1424490014.269; 6 | 2020-02-21 04:17:01 UTC | projects/project-id/logs/syslog | Feb 21 04:17:01 my-gce-instance /USR/SBIN/CRON[8082]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly) 7 | 2020-02-21 04:49:58 UTC | projects/project-id/logs/apache-access | 128.61.240.66 - - [21/Feb/2020:04:49:58 +0000] "GET / HTTP/1.0" 200 536 "-" "masscan/1.0 (https://github.com/robertdavidgraham/masscan)" 8 | 2020-02-21 05:17:01 UTC | projects/project-id/logs/syslog | Feb 21 05:17:01 my-gce-instance /USR/SBIN/CRON[9104]: (root) CMD ( cd / && run-parts --report /etc/cron.hourly) 9 | 2020-02-21 05:30:50 UTC | projects/project-id/log/syslogapache-access | 92.254.50.61 - - [21/Feb/2020:05:30:50 +0000] "GET /tmUnblock.cgi HTTP/1.1" 400 541 "-" "-"
App Engine 查詢範例
下列 BigQuery 查詢會擷取上個月失敗的 App Engine 要求：
SELECT timestamp AS Time, protoPayload.host AS Host, protoPayload.status AS Status, protoPayload.resource AS Path FROM (TABLE_DATE_RANGE(my_bq_dataset.appengine_googleapis_com_request_log_, DATE_ADD(CURRENT_TIMESTAMP(), -1, 'MONTH'), CURRENT_TIMESTAMP())) WHERE protoPayload.status != 200 ORDER BY time
以下是部分結果：
Row | Time | Host | Status | Path --- | ----------------------- | ------------------------------------- | ------ | ------ 6 | 2020-02-12 19:35:02 UTC | default.my-gcp-project-id.appspot.com | 404 | /foo?thud=3 7 | 2020-02-12 19:35:21 UTC | default.my-gcp-project-id.appspot.com | 404 | /foo 8 | 2020-02-16 20:17:19 UTC | my-gcp-project-id.appspot.com | 404 | /favicon.ico 9 | 2020-02-16 20:17:34 UTC | my-gcp-project-id.appspot.com | 404 | /foo?thud=%22what???%22
轉送記錄的 BigQuery 結構定義
路由記錄的 BigQuery 表格結構定義是以 LogEntry 類型的結構和記錄酬載的內容為基礎。Cloud Logging 也會運用規則，縮短稽核記錄和特定結構化酬載欄位的 BigQuery 結構定義欄位名稱。您可以在 BigQuery 介面中選取具有路由記錄項目的資料表，查看資料表結構定義。
欄位命名慣例
將記錄傳送至 BigQuery 時，以下提供了幾個適用於記錄項目欄位的命名慣例：
記錄項目欄位名稱的長度不得超過 128 個半形字元。
記錄項目欄位名稱只能使用英數字元。系統會從欄位名稱中移除任何不支援的字元，並以底線字元取代。舉例來說，
jsonPayload.foo%%會轉換為jsonPayload.foo__。即使經過轉換，記錄項目欄位名稱開頭仍須為英數字元，開頭的底線會一併移除。
如果是屬於
LogEntry類型中的記錄項目欄位，則對應的 BigQuery 欄位名稱與記錄項目欄位完全相同。如果是使用者提供的記錄項目欄位，則對應的 BigQuery 欄位名稱會標準化為小寫，但仍保留命名。
如果是結構化酬載中的欄位，只要當中沒有
@type指定碼，則會將對應的 BigQuery 欄位名稱標準化為小寫，但仍保留命名。如要瞭解內含
@type指定碼的結構化酬載，請參閱本頁的「具有@type的酬載欄位」一節。
以下範例說明如何運用這些命名慣例：
| 記錄項目欄位 | LogEntry 類型對應 |
BigQuery 欄位名稱 |
|---|---|---|
insertId |
insertId |
insertId |
textPayload |
textPayload |
textPayload |
httpRequest.status |
httpRequest.status |
httpRequest.status |
httpRequest.requestMethod.GET |
httpRequest.requestMethod.[ABC] |
httpRequest.requestMethod.get |
resource.labels.moduleid |
resource.labels.[ABC] |
resource.labels.moduleid |
jsonPayload.MESSAGE |
jsonPayload.[ABC] |
jsonPayload.message |
jsonPayload.myField.mySubfield |
jsonPayload.[ABC].[XYZ] |
jsonPayload.myfield.mysubfield |
具有 @type 的酬載欄位
本節將探討酬載中含有指定碼 @type 的記錄項目所對應的特殊 BigQuery 結構定義欄位名稱，這包括導向至 BigQuery 的稽核記錄項目。
記錄項目中的酬載可以包含結構化資料。任何結構化欄位都可以包含選用的類型指定詞，格式如下：
@type: type.googleapis.com/[TYPE]
命名規則說明為什麼稽核記錄項目的 protoPayload 欄位可能會對應到 BigQuery 結構定義欄位 protopayload_auditlog。
@type 的命名規則
含有類型指定碼的結構化欄位通常會採用 BigQuery 欄位名稱，且欄位名稱會加上 [TYPE]。[TYPE] 的值可以是任何字串。
@type 的命名規則僅適用於 jsonPayload 或 protoPayload 的頂層；系統會忽略巢狀欄位。處理頂層結構化酬載欄位時，Logging 會移除前置字串 type.googleapis.com。
例如，下表顯示頂層結構化酬載欄位與 BigQuery 欄位名稱的對應：
| 酬載 | 酬載 @type | 酬載欄位 | BigQuery 欄位名稱 |
|---|---|---|---|
jsonPayload |
(無) | statusCode |
jsonPayload.statusCode |
jsonPayload |
type.googleapis.com/abc.Xyz |
statusCode |
jsonpayload_abc_xyz.statuscode |
protoPayload |
(無) | statusCode |
protoPayload.statuscode |
protoPayload |
type.googleapis.com/abc.Xyz |
statusCode |
protopayload_abc_xyz.statuscode |
如果是含有類型指定碼的欄位，上述規則會有一些例外：
在 App Engine 要求記錄中，即使酬載包含類型指定碼，匯出到 BigQuery 的記錄酬載名稱也會是
protoPayload。Cloud Logging 會運用一些特殊規則，縮短稽核記錄的 BigQuery 結構定義欄位名稱。我們將在本頁面的「稽核記錄欄位」一節中討論。
範例
本範例說明 BigQuery 收到結構化酬載欄位時，如何命名及使用這些欄位。
假設記錄項目酬載的結構化方式如下：
jsonPayload: {
@type: "type.googleapis.com/google.cloud.v1.CustomType"
name_a: {
sub_a: "A value"
}
name_b: {
sub_b: 22
}
}
BigQuery 欄位的對應如下：
頂層結構化欄位
jsonPayload包含@type指定項目。其 BigQuery 名稱為jsonpayload_v1_customtype。系統會依據標準 BigQuery 命名規則處理巢狀欄位，因為類型指定碼規則不適用於巢狀欄位。
因此，記錄項目的酬載具有以下 BigQuery 名稱定義：
jsonpayload_v1_customtype
jsonpayload_v1_customtype._type
jsonpayload_v1_customtype.name_b
jsonpayload_v1_customtype.name_b.sub_b
jsonpayload_v1_customtype.name_a
jsonpayload_v1_customtype.name_a.sub_a
稽核記錄欄位
如果您未使用已路由至 BigQuery 的稽核記錄，可跳過這一節。
稽核記錄酬載欄位 protoPayload.request、protoPayload.response 和 protoPayload.metadata 都有 @type 指定碼，不過系統會將這些欄位視為 JSON 資料。也就是說，這些欄位的 BigQuery 結構定義名稱為附加 Json 的欄位名稱，且名稱中包含 JSON 格式的字串資料。
這兩組稽核記錄酬載欄位名稱如下表所示：
| 記錄項目欄位 | BigQuery 欄位名稱 |
|---|---|
protoPayload |
protopayload_auditlog |
protopayload.metadata |
protopayload_auditlog.metadataJson |
protoPayload.serviceData |
protopayload_auditlog.servicedata_v1_bigquery 範例： protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest |
protoPayload.request |
protopayload_auditlog.requestJson |
protoPayload.response |
protopayload_auditlog.responseJson |
請注意，serviceData 命名慣例僅適用於由 BigQuery 產生，且接著從 Cloud Logging 路由至 BigQuery 的稽核記錄。這些稽核記錄項目包含 serviceData 欄位，且具有 type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata 的 @type 指定碼。
範例
由 BigQuery 產生一個名稱如下的稽核記錄項目：
protoPayload.serviceData.tableInsertRequest
如果此記錄項目接著會路由至 BigQuery，tableInsertRequest 欄位會如何參照？在名稱縮短之前，BigQuery 中的對應欄位名稱為：
protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest
名稱縮短後，系統會參照 BigQuery 資料表中的相同欄位，如下所示：
protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
表格機構
本節將針對傳送至 BigQuery 的記錄，提供分區資料表的總覽。
將記錄檔轉送至 BigQuery 資料集時，Logging 會建立資料表來保留記錄項目。BigQuery 收到的第一個記錄項目會決定目的地 BigQuery 資料表的結構定義。BigQuery 會建立資料表，其欄位會根據第一個記錄項目的欄位和類型建立。後續的記錄項目可能會導致結構定義不相符。如要瞭解這些錯誤發生的時間和處理方式，請參閱「結構定義中的不相符處」。
Logging 會透過兩種資料表類型來整理路由的資料：日期區塊資料表和分區資料表。這兩種資料表類型會根據記錄項目的 timestamp 欄位分割記錄資料。不過，這兩種表格類型之間有兩個主要差異，如下所示：
效能：分區資料表會將大型資料表分割為較小分區，藉此提高查詢效能，並且可以透過減少查詢讀取的位元組數來控制費用。
表格名稱：表格類型會使用不同的命名慣例，請參閱下文。
表格機構
記錄項目會切割成 BigQuery 表格，這些表格的組織和名稱會根據項目的記錄檔名稱和時間戳記而定。
表格名稱的後置字串為日誌項目的 UTC 時間戳記，格式為 ISO 8601 基本格式 (YYYYMMDD)。
下表列出記錄名稱和記錄時間戳記如何對應至 BigQuery 中的資料表名稱：
| 記錄檔名稱 | 記錄項目 timestamp1 |
BigQuery 資料表名稱 (按日期分割) |
BigQuery 資料表名稱 (已劃分) |
|---|---|---|---|
syslog |
2017-05-23T18:19:22.135Z |
syslog_20170523 |
syslog |
apache-access |
2017-01-01T00:00:00.000Z |
apache_access_20170101 |
apache_access |
compute.googleapis.com/activity_log |
2017-12-31T23:59:59.999Z |
compute_googleapis_com_activity_log_20171231 |
compute_googleapis_com_activity_log |
1 記錄項目時間戳記以世界標準時間 (UTC) 表示。
建立分區資料表
建立匯出目的地以將記錄路由至 BigQuery 時，您可以使用日期區塊資料表或分區資料表。預設選項是日期資料分割的資料表：
如需建立接收器的操作說明，請參閱下列資源：
Google Cloud 控制台：將記錄檔轉送至支援的目的地。
Google Cloud CLI：
gcloud logging sinks create。
結構定義不符
BigQuery 收到的第一個記錄項目會決定目的地 BigQuery 資料表的結構定義。BigQuery 會建立資料表，其欄位會根據第一個記錄項目的欄位和類型建立。
當記錄項目寫入目的地資料表，且發生下列任一錯誤時，就會發生結構定義不相符的情況：
後續的記錄項目會變更資料表中現有欄位的欄位類型。
舉例來說，如果初始記錄項目的
jsonPayload.user_id欄位是string，則該記錄項目會為該欄位產生字串類型的表格。如果您之後開始將jsonPayload.user_id記錄為array，就會導致結構定義不相符。新的記錄項目包含不在目前結構定義中的欄位，如果將該欄位插入目的地資料表，就會超過 BigQuery 資料欄限制。
如果新欄位不會導致資料欄數量超出上限，目的地資料表就能接受該欄位。
BigQuery 在發現結構定義不相符時，會在對應的資料集中建立資料表，用於儲存錯誤資訊。資料表的類型會決定資料表名稱。日期分割資料表的命名格式為 export_errors_YYYYMMDD。分區資料表的命名格式為 export_errors。詳情請參閱「資料表組織」。
在轉送記錄項目時，Logging 會將訊息以批次的方式傳送至 BigQuery。BigQuery 會使用下列規則，判斷目前批次訊息中的記錄項目應寫入哪個資料表：
當欄位類型發生變更時，只有導致結構定義不相符的記錄項目才會寫入錯誤表格。目前批次訊息中未造成結構定義不相符的記錄項目會寫入原始目的地資料表。
如果超過資料欄上限，系統會將目前批次訊息中的所有記錄項目寫入錯誤表。
錯誤表格結構定義
錯誤表格包含 LogEntry 的資料，以及不相符的資訊：
logEntry：包含完整的記錄項目，但記錄項目會從 JSON 轉換為字串。schemaErrorDetail：包含 BigQuery 傳回的完整錯誤訊息。sink：包含記錄匯入端的完整資源路徑。logName：從LogEntry擷取。timestamp：從LogEntry擷取。receiveTimestamp：從LogEntry擷取。severity：從LogEntry擷取。insertId：從LogEntry擷取。trace：從LogEntry中擷取。resourceType：從LogEntry中擷取。
記錄會以以下方式將結構定義不相符的情形傳達給包含路由接收器的Google Cloud 專案：
- 專案擁有者會收到電子郵件。詳細資料包括： Google Cloud 專案 ID、接收器名稱和目的地。
- Google Cloud 控制台活動頁面顯示錯誤
Stackdriver Config error。詳細資料包括接收器名稱和目的地，以及導致錯誤的記錄項目範例連結。
避免日後發生欄位類型不符的情況
如要修正後續記錄項目的欄位類型不符問題，請修正欄位類型，使其符合目前的結構定義。如要瞭解如何修正欄位類型，請參閱「變更資料欄的資料類型」。
有時無法變更欄位類型，例如，您無法變更由 Google Cloud服務自動產生的記錄檔欄位類型。如無法變更欄位類型，為避免結構定義不相符，請重新命名資料表或變更接收器的參數，讓 Logging 在其他資料集中重新建立資料表。如需操作說明，請參閱「管理匯流程」。
疑難排解
如果接收器的目的地似乎缺少記錄檔，或是您懷疑接收器無法正確轉送記錄檔，請參閱「疑難排解：轉送記錄檔」。
定價
Cloud Logging 不會針對將記錄檔轉送至支援的目的地收費，但目的地可能會收取費用。除了 _Required 記錄檔值區，Cloud Logging 會針對將記錄檔串流至記錄檔值區，以及超過記錄檔值區預設保留期限的儲存空間收取費用。
複製記錄、建立記錄範圍或分析檢視畫面，或是透過 Logs Explorer 或 Log Analytics 頁面發出的查詢，Cloud Logging 不會收取費用。
如需詳細資訊，請參閱下列文件：
- Cloud Logging 定價摘要
目的地費用：
- 如果您傳送虛擬私人雲端流程記錄檔到 Cloud Logging 後又將其排除，系統會向您收取虛擬私人雲端流程記錄檔產生費用。