排查路由和接收器问题

使用接收器路由日志时,可能会发生以下情况之一:

  • 接收器目标位置似乎缺少日志。
  • 您会看到包含接收器配置错误信息的日志。
  • 您收到接收器包含错误的电子邮件通知。

本文档介绍与接收器相关的常见问题,以及如何使用 Cloud Console 查看配置错误或意外结果并进行问题排查。

目标位置缺少日志

最常见的接收器相关问题可能是接收器目标位置缺少日志。

在某些情况下,没有生成错误,但您可能会发现当尝试在目标位置访问日志时,日志不可用。如果您怀疑接收器未正确路由日志,请检查接收器的基于系统日志的指标:

  • exports/byte_count:路由的日志条目中的字节数。
  • exports/log_entry_count:已路由的日志条目数。
  • exports/error_count:路由失败的日志条目数。

此类指标具有按接收器名称和目标名称记录数量的标签,可让您了解接收器路由日志数据的操作是成功还是失败。如需详细了解如何查看指标,请参阅查看基于日志的指标

如果接收器指标表明接收器未按预期运行,以下是一些可能的原因以及解决方法:

  • 接收器的过滤条件不正确,无法捕获您希望在目标位置中看到的日志。

    将接收器的过滤条件复制到日志资源管理器中,以验证匹配的日志条目最近到达了 Logging;更新接收器,以更正过滤条件中的任何拼写错误或格式错误:

    转到日志浏览器

  • 自接收器创建或更新后,尚未收到任何匹配的日志条目;仅路由新的日志条目。

    请尝试等待 1 小时,然后再次查看目标位置。

  • 匹配的日志条目延迟到达。

    您可能需要等待一段时间才能在目标位置中查看日志。延迟的日志在将 Cloud Storage 存储桶配置为目标位置的接收器中尤为常见。请等待几小时,然后再次检查目标位置。

在更正所有错误并且 Logging 收到与您的过滤条件匹配的日志后,接收器会开始路由日志。

查看错误

对于每个受支持的接收器目标位置,Logging 都会为未正确配置的接收器提供错误消息。

您可以通过多种方式查看这些与接收器相关的错误;以下部分介绍了这些方法:

  • 查看为接收器生成的错误日志。
  • 通过电子邮件接收接收器错误通知。
  • 使用 Cloud Console 活动流

错误日志

详细检查接收器相关错误的建议方法是查看接收器生成的错误日志条目。如需详细了解如何查看日志,请参阅使用日志浏览器

您可以在 Google Cloud Console 的 Cloud Logging 查询构建器窗格中使用以下查询来查看接收器的错误日志;这一查询在 Logging API 或 gcloud 命令行工具中也有效。将变量 SINK_NAME 替换为您尝试进行问题排查的接收器的名称。您可以在 Google Cloud Console 的日志路由器页面找到接收器的名称。

logName:"logging.googleapis.com%2Fsink_error"
resource.type="logging_sink"
resource.labels.name="<var>SINK_NAME</var>"

例如,如果接收器的名称为 my-sink-123,则日志条目可能如下所示:

{
  "textPayload": "Cloud Logging export config error in my-logs-project, export sink my-sink-123: dataset_not_found ()",
  "insertId": "12akhzyb14452",
  "resource": {
    "type": "logging_sink",
    "labels": {
      "project_id": "my-logs-test-project",
      "destination": "",
      "name": "my-sink-123"
    }
  },
  "timestamp": "2021-08-02T17:01:28.620961700Z",
  "severity": "ERROR",
  "labels": {
    "error_code": "dataset_not_found",
    ...
    "destination": "bigquery.googleapis.com/projects/my-logs-project/datasets/my-dataset",
    "sink_id": "my-sink-123",
    "activity_type_name": "LoggingSinkConfigErrorV2"
  },
  "logName": "projects/cloud-logs-test-project/logs/logging.googleapis.com%2Fsink_error",
  "receiveTimestamp": "2021-08-02T17:01:30.148869575Z"
}

LogEntry 字段 labels 及其嵌套键值信息可帮助您定位接收器错误的来源;它包含受影响的资源、受影响的接收器和错误代码。labels.error_code 字段包含错误的简要说明,让您知道接收器的哪个组件需要重新配置。

您可以转到 Cloud Console 日志路由器更新接收器

转到日志路由器

电子邮件通知

如果您以技术重要联系人的身份订阅了 Google Cloud 项目或其父资源,您将收到接收器配置错误电子邮件通知。如果没有为资源配置任何技术重要联系人,则被列为资源的 IAM Project Owner roles/owner 的用户将收到电子邮件通知。

每个错误组每天发送一次电子邮件。该电子邮件包含以下信息:

  • 资源 ID:配置了接收器的 Cloud 项目或其他 Google Cloud 资源的名称。
  • 接收器名称:包含配置错误的接收器的名称。
  • 接收器目标位置:接收器的路由目标位置的完整路径;例如:bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
  • 错误代码:错误类别的简短说明例如:dataset_not_found
  • 错误详情:错误的详细信息,包括对底层错误进行问题排查的建议。

该电子邮件还包含 Cloud Console 中日志路由器页面的链接,您可以在该页面查看和管理接收器:

转到日志路由器

活动流

如需查看接收器的配置错误的删节版本,您可以使用 Google Cloud Console 活动流。执行以下操作:

  1. 验证您拥有正确的权限来查看活动流中的错误;您需要 Google Cloud 资源的 Owner 角色。

  2. 转到在其中创建接收器的 Cloud 项目或其他资源的活动流

    转到“活动流”

  3. 过滤条件面板中,依次选择活动类型 > 配置资源类型 > 日志导出接收器

  4. 调整日期/时间以查看相应时间范围内的接收器错误。

适用于该资源的所有接收器配置错误会在列表中显示为 Cloud Logging sink configuration error。每个错误都包含由故障接收器生成的其中一个日志条目的链接。如需详细了解相应的错误,请参阅错误日志部分。

接收器错误的类型

以下各部分介绍了接收器相关错误的几大类别以及如何排查这些错误。

目标位置不正确

如果您设置接收器后看到配置错误,说明 Logging 尝试路由日志时无法找到目标位置,则可能是以下原因导致的:

  • 在接收器的配置中,指定的接收器目标位置有拼写错误或其他格式错误。

    您需要更新接收器的配置以正确指定现有目标位置。

  • 指定的目标位置可能已被删除。

    您可以更改接收器的配置以使用其他现有目标位置,也可以重新创建同名的目标位置。

在任何一种情况下,如需解决任何问题,请转到 Cloud Console 中的日志路由器

转到日志路由器

在找到目标位置后,接收器将开始路由日志,并且 Logging 会收到与您的过滤条件匹配的新日志。

权限问题

如果接收器尝试路由日志条目但缺少接收器目标位置的相应 IAM 权限,则接收器会报告错误(您可以查看)并跳过该日志条目。

创建接收器时,您必须为接收器服务帐号授予相应的目标位置特定权限。在 Google Cloud Console 中,如果您在同一 Cloud 项目中创建接收器,则 Google Cloud Console 会自动分配这些权限。如果您在其他 Cloud 项目中创建接收器,或者使用 gcloud 命令行工具或 Logging API 创建接收器,则必须手动配置权限。

如果您看到接收器发生与权限相关的错误,请添加必要的目标位置权限,或者更新接收器以使用其他目标位置。如需了解如何更新这些权限,请参阅目标位置权限

在创建接收器之后,需要等一段时间才能使用接收器的新服务帐号授权写入目标位置。在更正所有权限并且 Logging 收到与您的过滤条件匹配的新日志后,接收器会开始路由日志。

组织政策问题

如果您尝试路由日志条目,但遇到组织政策限制 Logging 向接收器的目标位置写入数据,则接收器无法路由到所选目标位置和报告错误。

如果您看到与组织政策相关的错误,可以执行以下操作:

  • 针对目标位置更新组织政策,以移除阻止接收器路由日志条目的限制条件;此操作假设您拥有更新组织政策的相应权限。

  • 如果您无法更新组织政策,请在日志路由器中更新接收器,以使用符合要求的目标位置:

    转到日志路由器

当组织政策不再阻止接收器写入目标位置并且 Logging 收到与您的过滤条件匹配的新日志后,接收器会开始路由日志。

加密密钥问题

如果您使用加密密钥(无论是由 Cloud Key Management Service 管理还是由您管理)来加密接收器目标位置的数据,您可能会看到相关错误。以下是一些可能的问题以及解决方法:

  • 没有为包含 Cloud KMS 密钥的 Cloud 项目启用结算功能。

    • 即使接收器已成功创建并使用正确的目标位置,如果没有与包含密钥的 Cloud 项目关联的有效结算帐号,系统也会显示此错误消息。

    • 确保存在与包含密钥的 Cloud 项目关联的有效结算帐号。如果结算帐号未关联到 Cloud 项目,请为该 Cloud 项目启用结算功能,或使用关联了有效结算帐号的 Cloud 项目所包含的 Cloud KMS 密钥。

  • 找不到 Cloud KMS 密钥。

    • 未找到包含用于加密数据的 Cloud KMS 密钥的 Cloud 项目。

    • 请使用现有 Cloud 项目中的有效 Cloud KMS 密钥。

  • Cloud KMS 密钥的位置与目标位置不匹配。

    • 如果包含 Cloud KMS 密钥的 Cloud 项目位于与目标区域不同的区域,则加密将失败,并且接收器无法将数据路由到该目标。

    • 使用区域与接收器目标位置匹配的 Cloud 项目所包含的 Cloud KMS 密钥。

  • 加密密钥对接收器的服务帐号的访问遭拒。

    • 即使接收器已成功创建且具有正确的服务帐号权限,如果接收器目的地使用的加密密钥没有给服务帐户足够的权限来加密或解密数据,则会显示此错误消息。

    • 为目标位置中使用的密钥的接收器的 writerIdentity 字段中指定的服务帐号授予 Cloud KMS CryptoKey Encrypter/Decrypter 角色。此外,请确保已启用 Cloud KMS API。

配额问题

当接收器写入日志时,特定于目标位置的配额会应用于创建接收器的 Cloud 项目。如果配额用尽,接收器会停止将日志路由到目标位置。

例如,将数据路由到 BigQuery 时,您可能会看到一个错误,告知您数据集内某个表已超出每个表的流式插入配额。在这种情况下,可能是接收器在短时间内路由了太多日志条目。相同的概念适用于其他受支持的接收器目标位置,例如 Pub/Sub 主题。

如需解决配额耗尽问题,请更新接收器的过滤条件来匹配更少的日志条目,从而减少路由的日志数据量。您可以在过滤条件中使用 sample 函数来选择日志条目总数的一部分。

当您更新接收器以匹配更少的日志条目或刷新配额后,接收器会开始将日志路由到目标位置。

如需详细了解路由日志时可能适用的限制,请参阅相应目标位置的配额信息:

除了一般的接收器错误类型之外,以下是最常见的特定于目标位置的错误类型以及解决方法。

路由到 Cloud Storage 时的错误

以下是将日志路由到 Cloud Storage 时最常见的错误:

  • 延迟的日志条目:

    • 路由的日志条目每小时向 Cloud Storage 存储桶保存一批。第一批条目可能需要 2 到 3 个小时才会开始显示。

    • 带有后缀 An(即“Append”)的路由日志文件分片用于保存延迟的日志条目。 如果 Cloud Storage 目标位置发生服务中断,Cloud Logging 将缓冲数据,直到中断结束。

  • 无法授予正确的目标位置权限:

    • 即使使用正确的服务帐号权限成功创建了接收器,如果创建 Cloud Storage 存储桶时将存储桶的访问权限控制模型设置为统一访问权限,则仍会显示此错误消息。

    • 对于现有 Cloud Storage 存储桶,您可以使用权限标签页在存储桶创建后的前 90 天更改访问权限控制模型。对于新存储桶,请在创建存储桶时选择精细访问权限控制模型。如需了解详情,请参阅创建 Cloud Storage 存储桶

路由到 BigQuery 时的错误

以下是将日志路由到 BigQuery 时最常见的错误:

  • 表架构无效:

    • 流式传输到 BigQuery 数据集中的表的日志与当前表的架构不匹配。常见问题包括尝试路由具有不同数据类型的日志条目,从而导致架构不匹配。例如,日志条目中的一个字段是整数,而架构中的相应列为字符串类型。

    • 确保您的日志条目与表架构匹配。 修复错误源后,您可以重命名当前表,并让 Logging 再次创建该表。如需了解详情,请参阅 BigQuery 架构

  • 日志条目超出允许的时间范围:

    • 流式传输到分区 BigQuery 表的日志超出允许的时间范围。BigQuery 不接受日期距现在过于久远的日志(过去或未来)。

    • 您可以更新接收器,将这些日志路由到 Cloud Storage 并使用 BigQuery 加载作业。如需详细了解说明,请参阅 BigQuery 文档

  • 数据集不允许与日志接收器关联的服务帐号向其写入数据:

    • 即使使用正确的服务帐号权限成功创建了接收器,如果包含接收器目标位置的 Cloud 项目没有关联有效的结算帐号,则仍会显示此错误消息。

    • 确保您的 Cloud 项目关联了结算账号。如果接收器目标 Cloud 项目未关联结算帐号,请为该 Cloud 项目启用结算功能,或者更新接收器目标位置,使其位于关联了有效结算帐号的 Cloud 项目中。

路由到 Cloud Logging 存储桶时的错误

您可能遇到这样的情况:您可以在日志浏览器中查看自己从接收器中排除的日志。如果满足以下任一条件,您仍然可以查看这些日志:

  • 您正在生成日志的 Google Cloud 项目中运行查询。

    如需解决此问题,请确保您在正确的 Cloud 项目中运行查询。

  • 排除的日志已发送到多个日志存储桶;您看到的是要排除的同一日志的副本。

    如需解决此问题,请在日志路由器页面中检查您的接收器,确保没有将日志添加到其他接收器的过滤条件中。

  • 您可以访问发送日志的日志存储桶中的视图。在这种情况下,默认您可以查看这些日志。

    为避免在日志浏览器中看到这些日志,您可以将搜索范围优化为源 Cloud 项目或存储分区。