排查路由和存储日志问题

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

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

排查路由日志问题

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

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

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

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

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

logName:projects/PROJECT_ID

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

目标位置缺少日志

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

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

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

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

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

延迟时间

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

请尝试等待 1 小时，然后再次查看目标位置。
匹配的日志条目延迟到达。

您可能需要等待一段时间才能在目标位置查看日志。延迟日志对于已将 Cloud Storage 存储分区配置为目标位置的接收器尤其常见。请试着等几个小时，然后再次查看您的目的地。

查看范围/过滤器不正确

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

将搜索范围限定为一个或多个存储视图，如下所示：
- 如果您使用的是 Logs Explorer，请使用优化范围按钮。
- 如果您使用的是 gcloud CLI，请使用 gcloud logging read 命令并添加 --view=AllLogs 标志。
您用于选择和查看接收器目标位置中的数据的时间范围过窄。

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

接收器过滤条件有误

接收器的过滤条件不正确，没有捕获您希望在目标位置看到的日志。
- 使用 Google Cloud 控制台中的日志路由器修改接收器的过滤条件。如需验证您输入的过滤条件是否正确，请在修改接收器面板中选择预览日志。系统将在新标签页中打开日志浏览器，其中已预填充过滤条件。如需了解如何查看和管理接收器，请参阅管理接收器。

查看错误

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

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

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

错误日志

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

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

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

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 字段包含错误的简要说明，让您知道接收器的哪个组件需要重新配置。

如需更新接收器，请使用日志路由器。

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：

前往日志路由器

电子邮件通知

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

该电子邮件包含以下信息：

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

如需查看和管理接收器，请使用日志路由器。

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：

前往日志路由器

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

接收器错误的类型

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

目标位置不正确

如果您设置了接收器，但随后看到在 Logging 尝试路由日志时找不到目标位置的配置错误，则可能是以下几种原因造成的：

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

您需要更新接收器的配置以正确指定现有目标位置。
指定的目标位置可能已被删除。

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

无论是哪种情况，要解决任何问题，请转到日志路由器页面。

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：

前往日志路由器

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

管理接收器问题

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

权限问题

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

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

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

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

组织政策问题

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

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

更新目标位置的组织政策，以移除阻止接收器路由日志条目的限制条件；这假设您拥有更新组织政策的相应权限。如需查看说明，请参阅创建和修改政策。
如果您无法更新组织政策，请在日志路由器页面中更新您的接收器，以使用合规的目标位置。

在 Google Cloud 控制台的导航面板中，选择 Logging，然后选择日志路由器：
前往日志路由器

当组织政策不再阻止接收器写入目标位置并且 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 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 项目中运行查询。
排除的日志已发送到多个日志存储桶；您看到的是要排除的同一日志的副本。

如需解决此问题，请在日志路由器页面中检查您的接收器，确保您没有在其他接收器的过滤条件中包含日志。
您可以访问发送日志的日志存储桶中的视图。在这种情况下，默认您可以查看这些日志。

为避免在日志浏览器中看到这些日志，您可以缩小搜索范围，仅搜索源 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 权限，请执行以下操作：

在 Google Cloud 控制台的导航面板中，选择 IAM：
前往 IAM
在权限标签页中，按角色查看。您将看到一个表，其中包含与您的 Google Cloud 项目关联的所有 IAM 角色和主帐号。
在该表的过滤条件文本框中，输入 Logs Bucket Writer。

您会看到所有具有 Logs Bucket Writer 角色的主账号。如果主账号是服务帐号，则其 ID 包含字符串 gserviceaccount.com。
可选：如果您要移除某个服务帐号，使其无法将日志路由到您的 Google Cloud 项目，请选中该服务帐号的复选框，然后点击移除。

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

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

如果您使用日志浏览器访问这些日志并查看从 _Default 接收器中排除的日志，那么您的视图可能会限定在 Google Cloud 项目级别。

如需解决此问题，请在优化范围面板中选择按存储确定范围，然后选择 Google Cloud 项目中的 _Default 存储桶。您应该不会再看到已排除的日志。

排查路由和存储日志问题

排查路由日志问题

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

目标位置缺少日志

查看错误

错误日志

电子邮件通知

接收器错误的类型

目标位置不正确

管理接收器问题

权限问题

组织政策问题

加密密钥问题

配额问题

路由到 Cloud Storage 时的错误

路由到 BigQuery 时的错误

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

排查日志存储问题

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

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

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

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