本页面详细介绍了将日志条目从 Cloud Logging 路由到 BigQuery 时应用的格式设置和规则。
概览
您可以使用接收器将日志条目从 Cloud Logging 路由到 BigQuery。创建接收器时，将 BigQuery 数据集定义为目标位置。Logging 会将与接收器的规则匹配的日志条目发送到在该 BigQuery 数据集中为您创建的分区表。
从 Cloud Logging 接收的数据的 BigQuery 表架构基于 LogEntry 类型的结构和日志条目载荷的内容。Cloud Logging 还会应用规则来缩短审核日志和某些结构化载荷字段的 BigQuery 架构字段名称。
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 说明符为 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 会创建表来保存日志条目。Logging 使用两种表类型整理其路由的数据，这两种类型分别为：日期分片表和分区表。这两种表类型都会根据日志条目的 timestamp 字段对日志数据进行分区。但是，这两种表类型之间存在两个主要区别，如下所示：
性能：分区表会将较大的表划分为较小的分区，以便提高查询性能，从而通过减少查询读取的字节数来更好地控制 BigQuery 费用。
表命名法：这些表类型采用不同的命名惯例，如以下部分所述。
整理表
日志条目被分片为 BigQuery 表，这些表的组织和名称基于条目的日志名称和时间戳。
表名称的后缀为日志条目的日历日期 [采用 ISO 8601 基本格式 (YYYYMMDD)]。
下表举例说明了日志名称和示例时间戳与 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 logging sinks create。
架构不匹配
BigQuery 接收的第一个日志条目决定了目标 BigQuery 表的架构。该日志条目会生成一个表，该表的列基于日志条目的字段和字段类型。如果后续日志条目中出现新字段，则系统会更新表架构以包含新列。但是如果现有字段的字段类型发生了更改，则与该架构不匹配的较新日志条目会被丢弃。
例如，如果初始日志条目的 jsonPayload.user_id 字段为 string，则该日志条目会生成一个表，其中包含该字段的字符串类型。如果您随后开始将 jsonPayload.user_id 记录为 array，则这些日志条目不会插入到表中，并且会丢失。
Logging 通过以下方式将这些数据丢失情况传达给包含路由接收器的 Cloud 项目：
- 项目所有者会收到一封电子邮件。详细信息包括：Google Cloud 项目 ID、接收器名称和目标位置。
- Google Cloud Console“活动”页面会显示错误
Stackdriver Config error。详细信息包括接收器名称和目标位置，以及指向导致错误的日志条目示例的链接。 - 基于日志的系统指标
exports/error_count会告知您因错误而未路由的日志条目的总数。
要更正后续日志条目的问题，以避免继续丢失数据，请修正字段类型，使其与当前架构相匹配。您还可以重命名表或更改接收器的参数，以便 Logging 在其他数据集中重新创建该表。如需了解相关说明，请参阅更新接收器。
查看日志
您可以在 BigQuery 网页界面中选择包含从 Cloud Logging 中接收的日志条目的表，从而查看日志及其 BigQuery 架构。