导出日志的 BigQuery 架构

本页面详细介绍了将日志条目从 Cloud Logging 导出到 BigQuery 时应用的格式设置和规则。

Logging 会以一次一条记录的方式将日志记录数据流式插入 BigQuery，而不是使用加载作业。这种方法可让您在 BigQuery 中查询数据时避免因运行加载作业而产生的延迟。如需了解详情，请参阅将数据流式插入 BigQuery。

导出日志的 BigQuery 表格架构基于 LogEntry 类型的结构和日志载荷的内容。Cloud Logging 还会应用一些特殊规则来缩短审核日志的 BigQuery 架构字段名称的长度。您可以在 BigQuery 网页界面中选择包含导出日志条目的表，从而查看表格架构。

字段命名惯例

以下几项命名惯例适用于日志条目字段：

对于属于 LogEntry 类型的日志条目字段，对应的 BigQuery 字段名称与日志条目字段完全相同。
对于所有用户提供的字段，字母大小写均标准化为小写，而命名则保留下来。
- 对于结构化负载中的字段，只要 @type 说明符不存在，字母大小写就会标准化为小写，而命名则保留下来。
  
  如需了解存在 @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 说明符，那么结构化负载字段到 BigQuery 字段名称的对应关系会更加复杂。此内容将在下一部分中讨论。

带有 @type 的载荷字段

本部分介绍了负载包含类型说明符（@type 字段）的日志条目的特殊 BigQuery 架构字段名称。这包括在 BigQuery 中保存的导出审核日志条目。例如，本部分说明了审核日志条目的 protoPayload 字段可能对应于 BigQuery 架构字段 protopayload_auditlog 的原因。

架构命名规则

日志条目中的负载可以包含结构化数据，而结构化数据可以包含嵌套的结构化字段。任何结构化字段都可以包含以下格式的可选类型说明符：

@type: type.googleapis.com/[TYPE]

具有类型说明符的结构化字段通常被赋予 BigQuery 字段名称，其字段名称附加了 [TYPE]。[TYPE] 的值可以是任何字符串。

例如，下表显示了顶级结构化负载字段到 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`

如果 jsonPayload 或 protoPayload 包含其他结构化字段，那么这些内部字段的对应关系如下所示：

如果嵌套的结构化字段没有 @type 说明符，则其 BigQuery 字段名称与原始字段名称相同，只是它被标准化为小写字母。
如果嵌套的结构化字段有 @type 说明符，则其 BigQuery 字段名称附加了 [TYPE]（已重拼），且被标准化为小写字母。

对于具有类型说明符的字段，上述规则有一些例外情况：

在 App Engine 请求日志中，导出到 BigQuery 的日志中的负载名称为 protoPayload，即使该负载具有类型说明符也是如此。
Cloud Logging 会应用一些特殊规则来缩短审核日志的 BigQuery 架构字段名称的长度。这种情况在本页面的已导出审核日志架构字段部分进行了说明。

示例

下面的示例展示了结构化负载字段在导出到 BigQuery 后的命名方式和使用方式。

假设某个日志条目负载的结构如下：

jsonPayload: {
  name_a: {
    sub_a: "A value"
  }
  name_b: {
    @type: "type.googleapis.com/google.cloud.v1.SubType"
    sub_b: 22
  }
}

与 BigQuery 字段的对应关系如下所示：

jsonPayload 和 name_a 是结构化字段，但没有 @type 说明符。它们的 BigQuery 名称分别是 jsonPayload 和 name_a。
sub_a 和 sub_b 不是结构化字段，因此它们的 BigQuery 名称分别是 sub_a 和 sub_b。
字段 name_b 有一个 @type 说明符，其 [TYPE] 为 google.cloud.v1.SubType。因此，其 BigQuery 名称为 name_b_google_cloud_v1_subtype。

简而言之，系统为该日志条目的负载定义了以下 5 个 BigQuery 名称：

jsonPayload
jsonPayload.name_a
jsonPayload.name_a.sub_a
jsonPayload.name_b_google_cloud_v1_subtype
jsonPayload.name_b_google_cloud_v1_subtype.sub_b

已导出的审核日志中的字段

如果您不使用已导出到 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 说明符为 type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata。

示例

BigQuery 生成的审核日志条目有一个字段，名称如下：

protoPayload.serviceData.tableInsertRequest

如果随后将此日志条目导出到 BigQuery，那么 tableInsertRequest 字段名称是怎样的呢？在名称长度缩短之前，对应的导出字段名称将是：

protopayload_google_cloud_audit_auditlog.servicedata_google_cloud_bigquery_logging_v1_auditdata.tableInsertRequest

在名称长度缩短之后，BigQuery 表中会出现同一字段，如下所示：

protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest

分区表

本部分简要介绍了用于将日志导出至 BigQuery 的分区表。

将日志导出到 BigQuery 数据集时，Logging 会创建表以保存导出的日志条目。Logging 使用两种表类型整理其导出的数据，这两种类型分别为：日期分片表和分区表。这两种表类型都会根据日志条目的 timestamp 字段对日志数据进行分区。但是，这两个表类型之间存在两个主要区别：

性能：分区表会将较大的表划分为较小的分区，以便提高查询性能，从而通过减少查询读取的字节数来更好地控制 BigQuery 费用。
表命名法：这些表类型采用不同的命名惯例，如以下部分所述。

整理表

导出的日志条目位于 BigQuery 表中，该表的名称基于条目的日志名称和时间戳。

下表举例说明了日志名称和示例时间戳与 BigQuery 中表名称的对应关系：

日志名称	日志条目 `timestamp`	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`

创建分区表

在创建接收器以将日志导出到 BigQuery 时，您可以使用日期分片表或分区表。默认选项是日期分片表。

如需了解 Google Cloud Console 的使用说明，请转到使用日志查看器导出。

如需了解 Cloud SDK 命令行界面的使用说明，请转到 gcloud alpha logging sinks create。

架构不匹配

第一个导出的日志条目决定了目标 BigQuery 表的架构。日志条目会生成一个表，该表的列基于日志条目的字段和字段类型。如果后续日志条目中出现新字段，则会更新表架构。但是如果某个现有字段的值类型发生了更改，则会丢弃与该架构不匹配的较新日志条目。

例如，如果初始导出包含 jsonPayload.user_id 为 string 的日志条目，则该日志条目会生成一个表，其中包含该字段的字符串类型。如果您开始将 jsonPayload.user_id 记录为 array，则这些日志条目不会插入到表中，并且会丢失。

Logging 通过以下方式传达包含导出内容的 Google Cloud 项目的数据丢失情况：

项目所有者会收到一封电子邮件。详细信息包括：Google Cloud 项目 ID、接收器名称和导出目标位置。
Google Cloud Console“活动”页面会显示错误 Stackdriver Config error。详细信息包括接收器名称和导出目标位置，以及指向导致错误的日志条目示例的链接。
系统（基于日志的）指标 exports/error_count 会告知您因错误而未导出的日志条目的总数。

要更正后续日志条目的问题，以避免继续丢失数据，请修正字段类型，使其与当前架构相匹配。您还可以重命名表或更改接收器的参数，以便 Logging 在其他数据集中重新创建该表。如需查看说明，请转到更新接收器。

查看日志

要使用 BigQuery 网页界面查看日志，请选择包含已导出的日志条目的表。