本文說明如何找出從 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 結構定義欄位名稱，如要瞭解稽核記錄的命名規則，請參閱本頁的「稽核記錄欄位」一節。
記錄項目的酬載可包含結構化資料。任何結構化欄位都可以包含選用型別指定符，格式如下：
@type: type.googleapis.com/[TYPE]
「@type」的命名規則
如果結構化欄位有類型指定碼，通常會將 [TYPE] 附加至欄位名稱，做為 BigQuery 欄位名稱。[TYPE] 的值可以是任何字串。
記錄項目類型會決定含有 @type 規範符的欄位命名規則。如果記錄項目不是稽核記錄，這些規則只會套用至 jsonPayload 或 protoPayload 的頂層，系統會忽略巢狀欄位。如要瞭解稽核記錄的命名規則，請參閱本頁的「稽核記錄欄位」一節。
處理頂層結構化酬載欄位時，記錄檔會移除前置字元 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 的稽核記錄，可跳過這一節。
本節適用於可包含選用型別指定符的結構化欄位，格式如下：
@type: type.googleapis.com/[TYPE]
修改欄位名稱
如果稽核記錄包含具有 @type 指定碼的酬載，Cloud Logging 可能會修改附加至指定碼的 [TYPE] 值，然後再產生 BigQuery 欄位名稱。這些修改會縮短 BigQuery 欄位名稱。
記錄一律會從 [TYPE] 值中移除 type.googleapis.com 前置字元。下表說明 Logging 何時會縮短欄位名稱：
原始 [TYPE] 值 |
修改時間：[TYPE] |
|---|---|
google.cloud.audit.AuditLog |
AuditLog |
google.appengine.legacy.AuditData |
legacy.appengine |
google.appengine.v1alpha.AuditData |
v1alpha.appengine |
google.appengine.v1beta.AuditData |
v1beta.appengine |
google.appengine.v1beta4.AuditData |
v1beta4.appengine |
google.appengine.v1beta5.AuditData |
v1beta5.appengine |
google.appengine.v1.AuditData |
v1.appengine |
google.cloud.bigquery.logging.v1.AuditData |
v1.bigquery |
google.iam.v1.logging.AuditData |
v1.iam |
google.iam.admin.v1.AuditData |
v1.iam.admin |
google.type.Money |
money |
google.appengine.logging.v1.RequestLog |
舉例來說，假設稽核記錄項目包含下列內容：
{
logName: "projects/REDACTED/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload: {
@type: "type.googleapis.com/google.cloud.audit.AuditLog"
serviceData: {
@type: "type.googleapis.com/google.appengine.legacy.AuditData"
eventData: {
timezone: "UTC"
}
}
}
}
BigQuery 欄位名稱衍生自修改後的記錄項目，如下所示：
{
logName: "projects/REDACTED/logs/cloudaudit.googleapis.com%2Factivity"
protoPayload: {
@type: "AuditLog"
serviceData: {
@type: "legacy.appengine"
eventData: {
timezone: "UTC"
}
}
}
}
「@type」的命名規則
稽核記錄中有數個欄位可包含 @type 指定碼：
protoPayloadprotoPayload.serviceDataprotoPayload.requestprotoPayload.responseprotoPayload.metadata
request、response 和 metadata 欄位會視為 JSON 資料。也就是說，這些欄位的 BigQuery 結構定義名稱為附加 Json 的欄位名稱，且名稱中包含 JSON 格式的字串資料。
這兩組稽核記錄酬載欄位名稱如下表所示：
| 記錄項目欄位 | BigQuery 欄位名稱 |
|---|---|
protoPayload |
protopayload_auditlog |
protopayload.metadata |
protopayload_auditlog.metadataJson |
protoPayload.request |
protopayload_auditlog.requestJson |
protoPayload.response |
protopayload_auditlog.responseJson |
protoPayload.serviceData |
protopayload_auditlog.servicedata_v1_bigquery 範例： protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest |
protoPayload.status.code |
protoPayload_auditlog.statuscode |
請注意，serviceData 命名慣例僅適用於由 BigQuery 產生、且接著從 Cloud Logging 傳送至 BigQuery 的稽核記錄。這些稽核記錄項目包含 serviceData 欄位，且具有 @type 指定碼 type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata。
範例
由 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 會根據第一個記錄項目的欄位及其類型建立資料表。後續記錄項目可能會導致結構定義不符。如要瞭解發生這些情況的時間和處理方式，請參閱「結構定義不符」。
記錄檔會將路由資料整理成兩種資料表：日期分片資料表和分區資料表。這兩種資料表類型都會根據記錄項目的 timestamp 欄位，將記錄資料分區。不過，這兩種表格類型有兩項主要差異，如下所示：
效能：分區資料表會將大型資料表分割為多個較小的分區，因此您可以提高查詢效能，並減少查詢讀取的位元組數，進一步控管 BigQuery 費用。
資料表命名：資料表類型採用不同的命名慣例，詳情請參閱下節。
表格機構
系統會將記錄項目分片到 BigQuery 資料表中，這些資料表的結構和名稱是根據項目的記錄檔名稱和時間戳記而定。
資料表名稱會附加記錄項目的世界標準時間時間戳記日曆日期，並使用 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 會針對將記錄檔串流至記錄檔值區，以及儲存時間超過記錄檔值區預設保留期限的記錄檔收費。
Cloud Logging 不會收取複製記錄、建立記錄範圍或分析檢視區塊的費用，也不會收取透過 Logs Explorer 或記錄檔分析頁面發出查詢的費用。
如需詳細資訊，請參閱下列文件：
- Cloud Logging 定價摘要
目的地費用：
- 如果您將虛擬私人雲端流程記錄傳送至 Cloud Logging 後又將其排除，系統就會向您收取虛擬私人雲端流程記錄產生費用。