导出日志的 BigQuery 架构

导出日志的 BigQuery 表架构基于 LogEntry 类型的结构和日志负载的内容。Stackdriver 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 的原因。

目前,BigQuery 中的审核日志条目有两种架构。两种架构表示某些审核日志负载信息目前在两个不同的 BigQuery 字段中存在重复,这两个字段包含不同格式的信息:一个旧的“扩展”字段名称和一个新的“紧凑”字段名称。2019 年 3 月 1 日起,旧的架构(字段名称)将被移除。如需了解详情,请参阅下面的迁移到最新架构部分。

架构命名规则

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

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

具有类型说明符的结构化字段通常被赋予 BigQuery 字段名称,其字段名称附加了 [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

如果 jsonPayloadprotoPayload 包含其他结构化字段,那么这些内部字段的对应关系如下所示:

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

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

  • 在 App Engine 请求日志中,导出到 BigQuery 的日志中的负载名称为 protoPayload,即使该负载具有类型说明符也是如此。您可以在查询的示例 App Engine 日志查询中看到这种情况。

  • Stackdriver Logging 会应用一些特殊规则来缩短审核日志的 BigQuery 架构字段名称的长度。详细内容将在下面的审核日志架构字段部分讨论。

  • 导出到 BigQuery 的审核日志以更新后的紧凑格式编写。某些负载信息在两个不同的字段中暂时存在重复。如需了解详情,请参阅迁移到最新架构

示例

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

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

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

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

  • 字段 jsonPayloadname_a 经过结构化处理,但没有 @type 说明符。它们的 BigQuery 名称分别是 jsonPayloadname_a

  • 字段 sub_asub_b 没有经过结构化处理,因此它们的 BigQuery 名称分别是 sub_asub_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 的审核日志,则可以跳过本部分。

旧的(“扩展”)审核日志负载字段在 Stackdriver 中均具有类型说明符(@type 字段)。它们对应的 BigQuery 字段名称是专门构造的,以免长度过长。

新的(“紧凑”)审核日志负载字段 protoPayload.requestprotoPayload.responseprotoPayload.metadata 具有 @type 说明符,但被视为 JSON 数据。也就是说,这些字段的 BigQuery 架构名称是附加了 Json 的字段名称,其中包含 JSON 格式的字符串数据。

下表列出了两组审核日志负载字段名称:

日志条目字段 扩展(旧的)BigQuery 字段名称 紧凑(新的)BigQuery 字段名称
protoPayload protopayload_auditlog 相同
protopayload.metadata protopayload_auditlog.metadata_* protopayload_auditlog.metadataJson
protoPayload.serviceData protopayload_auditlog.servicedata_v1_bigquery
示例:protopayload_auditlog.servicedata_v1_bigquery.tableInsertRequest
相同
protoPayload.request protopayload_auditlog.request_[Vn]_[PROTO_NAME]
示例:protopayload_auditlog.request_v2_listlogsinksrequest
protopayload_auditlog.requestJson
protoPayload.response protopayload_auditlog.response_[Vn]_[PROTO_NAME]
示例:protopayload_auditlog.response_v2_listlogsinksresponse
protopayload_auditlog.responseJson

您需要在 2019 年 3 月 1 日之前修改查询,以使用新的紧凑架构(字段名称),届时旧的扩展架构(字段名称)将被移除。

请注意有关审核日志命名的以下详细信息:

  • serviceData 命名规则针对的是由 BigQuery 生成并随后导出到 BigQuery 的审核日志。这些审核日志条目包含 serviceData 字段,其 @type 说明符为:

    type.googleapis.com/google.cloud.bigquery.logging.v1.auditdata
    
  • 扩展(旧的)字段 requestresponse 的命名规则假定它们的类型说明符遵循一种常见模式:

    [GOOGLE_SERVICE].[Vn].[PROTO_NAME]
    

    例如,在 request 字段中,说明符可以是:

    google.logging.v2.ListLogSinksRequest
    

    用下划线替换英文句点并将字母改为小写后,会产生下面这样典型的字段名称:

    request_google_logging_v2_listlogsinksrequest
    

    专门构造的架构字段名称如下:

    request_v2_listlogsinksrequest
    

    如果遇到模式不同的类型说明符,可以查看一些导出的日志条目,看看导出的字段名称长度是如何缩短的。

示例

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 中的审核日志条目有“扩展”和“紧凑”这两组字段名称2019 年 3 月 1 日起,扩展的字段名称组将被移除。请检查您的查询,并确定是否需要迁移到新的字段名称组:

  • 如果您目前在任何 BigQuery 查询的导出审核日志中都没有使用 requestresponserequestMetadata 字段,那么此次迁移不会影响到您。您可以跳过本部分。

  • 如果您是首次使用 requestresponserequestMetadata 字段,请从一开始就使用紧凑(新的)名称。为新服务生成的所有审核日志都将仅使用新的紧凑格式。您可以跳过本部分。

  • 如果您在任何 BigQuery 查询的导出审核日志中使用了 requestresponserequestMetadata 字段,且使用的是扩展(旧的)字段名称,请尽快改用紧凑(新的)名称。如需查看有关如何更新查询的示例,请阅读本部分并参阅更新查询

此更改会同时影响管理员活动和数据访问审核日志,将它们从当前的扩展格式(具有任意数量的字段)转换为更新后的紧凑 JSON 格式。对于现有的审核日志,Stackdriver Logging 已经编写了新的紧凑格式:

紧凑架构

在 2019 年 3 月 1 日之前,您可以在 BigQuery 中看到这两种格式,届时扩展格式将被移除。

导出非审核日志不受影响。将审核日志导出到 BigQuery 以外的位置也不受影响。

更新查询

对于从扩展字段名称到紧凑字段名称这项变化,审核日志架构字段中的表列出了受此影响的字段。如果您要查询这些字段中的任何一个,则需要检查 BigQuery 查询,并在 2019 年 3 月 1 日之前根据需要进行修改,届时旧的字段将被移除。

要更新查询,您需要使用 BigQuery JSON_EXTRACT() 方法。这些字段中的 @type 说明符应被视为对 JSON 数据内容的说明。

例如,选择其中一个 createSinkRequest 字段的查询(使用的是扩展字段名称)可能如下所示:

 SELECT protopayload_auditlog.request_v2_createsinkrequest.sink.destination
 as dest FROM ...

更改为紧凑字段名称后,具体语法将如下所示:

SELECT JSON_EXTRACT(protopayload_auditlog.requestJson, '$.sink.destination')
as dest FROM ...

查看审核日志

对于现有的审核日志,Stackdriver Logging 同时编写了新的紧凑格式和旧的扩展格式。在 2019 年 3 月 1 日之前,您可以在 BigQuery 中看到这两种格式,届时扩展格式将被移除。

要查看审核日志,请在 BigQuery 网页界面中选择包含导出日志条目的表。

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
Stackdriver Logging
需要帮助?请访问我们的支持页面