本页面详细介绍了将日志条目从 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 表,这些表的组织和名称基于条目的日志名称和时间戳。
表名称的后缀为日志条目的日历日期 [采用 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 表的架构。日志条目会生成一个表,该表的列基于日志条目的字段和字段类型。如果后续日志条目中出现新字段,则会更新表架构。但是如果某个现有字段的值类型发生了更改,则会丢弃与该架构不匹配的较新日志条目。
例如,如果初始导出包含 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 网页界面查看日志,请选择包含已导出的日志条目的表。