查看路由到 BigQuery 的日志

本文档介绍了如何查找从 Cloud Logging 路由到 BigQuery 表的日志条目。Logging 小批量将流式日志记录数据发送到 BigQuery,这样您可以在不运行加载作业的情况下查询数据。为帮助您创建查询并了解 BigQuery 表的格式,本文档还介绍了路由日志的 BigQuery 架构

通常,日志条目会在一分钟内显示在 BigQuery 中。但是,创建新表后,您可能需要等待几分钟才能看到第一批日志条目。

准备工作

如需查看接收器的概念性讨论,请参阅路由和存储模型概览:接收器

如需了解如何路由日志,请参阅将日志路由到支持的目标位置

如需了解路由的日志条目字段的命名方式,请参阅路由日志的 BigQuery 架构

查看日志

如需查看路由到 BigQuery 的日志,请执行以下操作:

  1. 在 Google Cloud 控制台中,转到 BigQuery 页面:

    前往 BigQuery Studio

    您也可以使用搜索栏查找此页面。

  2. 浏览器面板中,展开您的项目并选择数据集。

    日志条目显示在详细信息标签页中,您也可以通过查询表来返回数据。

查询示例

如需了解 BigQuery 查询语法,请参阅查询参考文档表通配符函数(支持跨多个表进行查询)以及展平运算符(支持显示重复字段中的数据)特别有用。

Compute Engine 查询示例

以下 BigQuery 查询可检索数天内多种日志类型的日志条目:

  • 该查询搜索日志 syslogapache-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 架构字段名称。这包括路由到 BigQuery 的审核日志条目。

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

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

命名规则说明了审核日志条目的 protoPayload 字段可能对应于 BigQuery 架构字段 protopayload_auditlog 的原因。

@type 的命名规则

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

@type 的命名规则仅适用于 jsonPayloadprotoPayload 的顶级;忽略嵌套字段。在处理顶级结构化载荷字段时,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.requestprotoPayload.responseprotoPayload.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 会创建表来保存日志条目。BigQuery 收到的第一个日志条目决定了目标 BigQuery 表的架构。BigQuery 会创建一个表,其列基于第一个日志条目的字段及其类型。后续日志条目可能会导致架构不匹配。如需了解这些错误何时发生以及如何处理它们,请参阅架构不匹配

Logging 使用两种表类型整理其路由的数据,这两种类型分别为:日期分片表分区表。这两种表类型都会根据日志条目的 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 时,您可以使用日期分片表或分区表。默认选择是日期分片表:

如需了解如何创建接收器,请参阅以下资源:

架构不匹配

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

Logging 通过以下方式将架构不匹配问题传达给包含路由接收器的 Google Cloud 项目:

  • 项目所有者会收到一封电子邮件。详细信息包括:Google Cloud 项目 ID、接收器名称和目标位置。
  • Google Cloud 控制台的“活动”页面会显示错误 Stackdriver Config error。详细信息包括接收器名称和目标位置,以及指向导致错误的日志条目示例的链接。

防止将来出现字段类型不匹配的情况

如需更正后续日志条目的字段不匹配问题,请修复字段类型,使得它与当前架构匹配。如需了解如何修正字段类型,请参阅更改列的数据类型

有时,字段类型无法更改,例如,您无法更改 Google Cloud 服务自动生成的日志的字段类型。为防止在无法更改字段类型时架构不匹配,请重命名表或更改接收器的参数,以便 Logging 在其他数据集中重新创建表。如需查看相关说明,请参阅管理接收器

问题排查

如果接收器的目标位置似乎缺少日志,或者您以其他方式怀疑接收器未正确路由日志,请参阅排查路由日志问题

价格

Cloud Logging 不会将日志路由到受支持的目的地;但是,该目的地可能会产生费用。除 _Required 日志存储桶外,Cloud Logging 会针对将日志流式传输到日志存储桶以及超出日志存储桶默认保留期限的存储收取费用。

Cloud Logging 不会就复制日志或通过日志浏览器页面或日志分析页面发出的查询收费。

有关详情,请参阅以下文档: