排查路由和存储日志问题

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

如需了解有关在接收器目标位置使用日志的一般信息，请参阅 查看接收器目标位置中的日志。

排查路由日志问题

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

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

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

若要解决此问题，请更新 排除过滤器 用于将日志路由到目标位置的接收器。利用排除过滤器，您可以 所选日志不会路由到目标位置。

例如，假设您创建了一个汇总接收器，用于将组织中的日志路由到某个目标位置。要从特定来源中排除日志， 将项目发送到目标位置 将以下排除过滤条件添加到接收器：

logName:projects/PROJECT_ID

您还可以使用逻辑或运算符排除多个项目中的日志 运算符来联接 logName 子句。

目标位置缺少日志

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

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

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

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

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

延迟时间

  • 自您创建或更新后，未收到任何匹配的日志条目 水槽；系统仅会路由新的日志条目

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

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

    您可能需要等待一段时间才能在目标位置中查看日志。 延迟日志 对于配置了 Cloud Storage 的接收器来说尤其常见 作为目标位置 请尝试等待几个小时，然后查看您的 目标。

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

  • 您用于在 Logging 存储桶目标位置查看日志的范围不正确。

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

    • 如果您使用的是日志浏览器，请使用 优化范围 按钮。

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

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

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

接收器过滤条件出错

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

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

查看错误

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

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

  • 查看为接收器生成的错误日志。
  • 通过电子邮件接收接收器错误通知。

错误日志

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

您可以在查询编辑器窗格中使用以下查询 日志浏览器，用于查看接收器的错误日志。相同的查询在 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。
  • 错误详情：错误的详细信息，包括对底层错误进行问题排查的建议。

要查看和管理接收器，请使用日志路由器页面：

前往日志路由器

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

接收器错误的类型

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

目标位置不正确

如果您设置了接收器，但之后看到 在 Logging 尝试路由日志时找不到，以下是 一些可能的原因：

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

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

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

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

为了解决这些类型的失败问题 修改接收器。 例如，您可以使用日志路由器页面修改接收器：

前往日志路由器

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

管理接收器问题

如果您停用了接收器以停止将日志存储在日志存储分区中，但仍看到日志正在路由，请等待几分钟，以便系统应用对接收器所做的更改。

权限问题

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

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

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

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

组织政策问题

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

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

  • 更新目标位置的组织政策以移除限制条件 阻止接收器路由日志条目；前提条件是 更新组织政策的相应权限。对于 请参阅创建和修改政策。

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

    前往日志路由器

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

加密密钥问题

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

  • 以下项目所属的 Google Cloud 项目尚未启用结算功能： Cloud KMS 密钥。

    • 即使使用正确的目标位置成功创建了接收器， 如果没有有效的结算账号，系统会显示此错误消息 与该密钥所属的 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 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 支持将嵌套数据加载到其表中。但是，从 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 存储桶时的错误

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

  • 您在生成 日志。

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

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

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

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

    为避免在日志浏览器中看到这些日志，您可以 缩小搜索范围 添加到源 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 项目。

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

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

  4. 可选：如果您希望移除服务账号，使其无法路由 将日志复制到您的 Google Cloud 项目，请选择 复选框 对应的服务账号，然后点击移除。

为什么我已将 Google Cloud 项目的日志从 _Default 接收器中排除，但仍会看到这些日志？

您可能正在 集中管理的 Google Cloud 项目 可汇总整个组织的日志

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

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