排查路由和存储日志问题

本文档介绍了常见的路由和存储问题，以及如何使用Google Cloud 控制台查看配置错误或意外结果并进行问题排查。

如需简要了解如何查看日志数据，请参阅查看接收器目标位置中的日志。

排查日志路由问题

本部分介绍了如何排查路由日志条目时的常见问题。

目标位置包含不需要的日志条目

您正在查看路由到某个目标位置的日志条目，并确定该目标位置包含不需要的日志条目。

如需解决此问题，请更新将日志条目路由到目标位置的接收器的排除项过滤条件。借助排除项过滤条件，您可以排除所选日志条目，使其不会路由到目标位置。

例如，假设您创建了一个汇总接收器，以将组织中的日志条目路由到目标位置。如需排除特定项目中的日志条目，使其不会路由到目标位置，请将以下排除项过滤条件添加到接收器中：

logName:projects/PROJECT_ID

您还可以使用逻辑 OR 运算符联接 logName 子句，从而排除多个项目中的日志条目。

目标位置缺少日志条目

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

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

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

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

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

延迟时间

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

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

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

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

查看范围/过滤条件不正确

• 您用于查看日志存储桶中存储的日志条目的范围不正确。

  将搜索范围限定为一个或多个日志视图，如下所示：

  • 如果您使用的是Logs Explorer，请使用优化范围按钮。

  • 如果您使用的是 gcloud CLI，请使用 gcloud logging read 命令并添加 --view=AllLogs 标志。

• 您用于在接收器目标位置中选择和查看数据的时间范围过窄。

  在接收器目标位置选择数据时，请尝试扩大所用的时间范围。

接收器过滤条件中的错误

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

  使用 Google Cloud 控制台中的日志路由器修改接收器的过滤条件。如需验证您输入的过滤条件是否正确，请在修改接收器面板中选择预览日志。此操作会在新的标签页中打开Logs Explorer且其中预填充了过滤条件。如需了解如何查看和管理接收器，请参阅管理接收器。

查看错误

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

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

• 查看为接收器生成的错误日志。
• 通过电子邮件接收接收器错误通知。 此邮件的发件人为 logging-noreply@google.com。

错误日志

要详细检查接收器相关错误，建议查看接收器生成的错误日志条目。如需详细了解如何查看日志条目，请参阅使用 Logs Explorer 查看日志。

您可以在 Logs Explorer 的查询编辑器窗格中使用以下查询来查看接收器的错误日志。相同的查询在 Logging API 和 gcloud CLI 中均有效。

在复制查询之前，请将变量 SINK_NAME 替换为您尝试进行问题排查的接收器的名称。您可以在 Google Cloud 控制台的日志路由器页面找到接收器的名称。

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

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

{
   errorGroups: [
   0: {
   id: "COXu96aNws6BiQE"
   }]
   insertId: "170up6jan"
   labels: {
      activity_type_name: "LoggingSinkConfigErrorV2"
      destination: "pubsub.googleapis.com/projects/my-project/topics/my-topic"
      error_code: "topic_not_found"
      error_detail: ""
      sink_id: "my-sink-123"
   }
   logName: "projects/my-project/logs/logging.googleapis.com%2Fsink_error"
   receiveTimestamp: "2024-07-11T14:41:42.578823830Z"
   resource: {
   labels: {
      destination: "pubsub.googleapis.com/projects/my-project/topics/my-topic"
      name: "my-sink-123"
      project_id: "my-project"
   }
   type: "logging_sink"
   }
   severity: "ERROR"
   textPayload: "Cloud Logging sink configuration error in my-project, sink my-sink-123: topic_not_found ()"
   timestamp: "2024-07-11T14:41:41.296157014Z"
}

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

如需解决此失败问题，请修改接收器。例如，您可以使用日志路由器页面修改接收器：

前往日志路由器

电子邮件通知

重要联系人会向分配给 Google Cloud 项目或其父资源的技术通知类别的联系人发送接收器配置错误邮件通知。如果资源没有配置技术通知联系人，则被列为资源的 IAM Project Owner roles/owner 的用户将收到邮件通知。

该邮件包含以下信息：

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

此邮件的发件人为 logging-noreply@google.com。

如需查看和管理您的接收器，请使用日志路由器页面：

前往日志路由器

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

接收器错误的类型

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

目标位置不正确

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

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

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

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

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

如需解决此类故障，请修改接收器。例如，您可以使用日志路由器页面修改接收器：

前往日志路由器

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

管理接收器问题

如果您停用某个接收器以停止在日志存储桶中存储日志条目，但仍看到日志条目正在被路由，请等待几分钟，让接收器的更改生效。

权限问题

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

创建接收器时，您必须为接收器服务账号授予相应的目标位置权限。在 Google Cloud 控制台中，如果您在同一Google Cloud 项目中创建接收器，则 Google Cloud 控制台通常会自动分配这些权限。不过，如果您在其他Google Cloud 项目中创建接收器，或者使用 gcloud CLI 或 Logging API 创建接收器，则必须手动配置权限。

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

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

组织政策问题

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

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

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

  您可以检查是否存在资源位置限制 (constraints/gcp.resourceLocations)。此限制条件决定了可以存储数据的位置。此外，某些服务支持可能会影响日志接收器的限制条件。例如，选择 Pub/Sub 目标时可能会受到一些限制。如需查看可能的限制条件列表，请参阅组织政策限制条件。

  如需了解相关说明，请参阅创建和修改政策。

• 如果您无法更新组织政策，请在日志路由器页面中更新接收器，以使用合规的目标位置。

  前往日志路由器

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

加密密钥问题

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

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

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

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

• 找不到 Cloud KMS 密钥。

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

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

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

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

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

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

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

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

配额问题

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

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

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

当配额可用时，接收器会将日志条目路由到接收器的目标位置。

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

• Cloud Logging：配额和限制

• Cloud Storage：配额和限制

• BigQuery：配额和限制

• Pub/Sub：配额和限制

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

路由到 Cloud Storage 时的错误

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

• 延迟的日志条目：

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

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

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

  • 验证日志接收器的服务账号是否具有正确的权限。如需了解详情，请参阅本文档的权限问题部分。

路由到 BigQuery 时的错误

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

• 表架构无效：

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

  • 确保您的日志条目与表架构匹配。 修复错误源后，您可以重命名当前表，并让 Logging 再次创建该表。

  • BigQuery 支持将嵌套数据加载到其表中。但是，从 Logging 加载数据时，列的嵌套深度上限是 13 层。

  当 BigQuery 识别到架构不匹配时，会在相应的数据集中创建一个表来存储错误信息。表的类型决定了表名称。对于日期分片表，命名格式为 export_errors_YYYYMMDD。对于分区表，命名格式为 export_errors。如需了解错误表的架构，以及如何防止将来出现字段类型不匹配的问题，请参阅架构中的不匹配问题。

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

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

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

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

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

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

• 数据集包含重复的日志条目：

  • 如果将日志条目流式传输到 BigQuery 时出现失败问题（包括因重试或配置错误导致的失败），可能会出现重复的日志条目。Cloud Logging 会在查询时对具有相同 timestamp 和 insertId 的日志条目进行去重。BigQuery 不会消除重复的日志条目。

  • 如需忽略 BigQuery 中的重复日志条目，请在查询中添加 SELECT DISTINCT 子句。例如：

  SELECT DISTINCT insertId, timestamp FROM TABLE_NAME
  

• 日志条目会在 Cloud Logging 突发事件发生后进行回填：

  Logging 会在 Cloud Logging 突发事件导致无法将日志数据路由到 BigQuery 时，自动生成带有 backfill_ 前缀的表，作为回填操作的一部分。

  带有 backfill_ 前缀的表包含在突发事件发生时间范围内要路由到 BigQuery 的所有日志条目。这些表可能包含一些已成功路由到接收器指定的表的日志条目。

  为防止数据重复，我们建议将回填表中的数据合并到原始表中，然后删除回填表。

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

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

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

  如需解决此问题，请验证您是否在正确的Google Cloud 项目中运行查询。

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

  如需解决此问题，请在日志路由器页面中检查接收器，以验证是否没有将日志条目添加到其他接收器的过滤条件中。

• 您有权访问日志条目发送到的日志存储桶中的视图。在这种情况下，默认您可以看到这些日志条目。

  为避免在 Logs Explorer 中看到这些日志条目，您可以将搜索范围优化为来源 Google Cloud 项目或存储桶。

排查存储日志问题

为什么我无法删除此存储桶？

如果要尝试删除存储桶，请执行以下操作：

• 确保您拥有删除存储桶存储桶的适当权限。如需查看所需权限的列表，请参阅使用 IAM 进行访问权限控制。

• 通过列出存储桶的特性来确定存储桶是否已锁定。如果存储桶已被锁定，请检查存储桶的保留期限。在存储桶中的所有日志都达到存储桶的保留期限之前，您无法删除锁定的存储桶。

• 验证日志存储桶是否没有关联的 BigQuery 数据集。您无法删除具有关联的数据集的日志存储桶。

  在对具有关联的数据集的日志存储桶运行 delete 命令时，响应中会显示以下错误：

  FAILED_PRECONDITION: This bucket is used for advanced analytics and has an active link. The link must be deleted first before deleting the bucket
  

  如需列出与日志存储桶关联的链接，请运行 [gcloud logging links list][link-list] 命令或运行 projects.locations.buckets.links.list API 方法。

哪些服务账号会将日志路由到我的存储桶？

如需确定是否有任何服务账号具有将日志路由到存储桶的 IAM 权限，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 IAM 页面：

   前往 IAM

   如果您使用搜索栏查找此页面，请选择子标题为 IAM 和管理的结果。

2. 在权限标签页中，按角色进行查看。您会看到一个表，其中包含与您的Google Cloud 项目关联的所有 IAM 角色和主账号。

3. 在该表的过滤条件文本框 filter_list中，输入 Logs Bucket Writer。

   您会看到具有 Logs Bucket Writer 角色的所有主账号。如果主账号是服务账号，则其 ID 包含字符串 gserviceaccount.com。

4. 可选：如果您要移除能够将日志路由到您的 Google Cloud 项目的服务账号，请选中该服务账号的复选框 check_box_outline_blank，然后点击移除。

为什么即使我从 _Default 接收器中排除了某个 Google Cloud 项目的日志，但我还是会看到它们？

您正在查看集中式 Google Cloud 项目的日志存储桶中的日志，其中汇总了整个组织中的日志。

如果您使用 Logs Explorer 访问这些日志，并看到已从 _Default 接收器中排除的日志，则您的视图可能已设置为Google Cloud 项目级。

如需解决此问题，请在优化范围菜单中选择日志视图，然后选择与Google Cloud 项目的 _Default 存储桶关联的日志视图。您应该不会再看到已排除的日志。