排查问题

本页面包含 Trace 的问题排查信息。

已知问题

本部分列出了已知问题：

• 使用 Telemetry API 写入到您的 Google Cloud 项目的 span 无法通过 Cloud Trace API 访问。例如，如果您尝试列出这些跟踪记录，则该命令会失败，并显示 404 Not Found 错误。

排查 Observability Analytics 问题

本部分介绍了如何解决在使用 Observability Analytics 查询跟踪记录数据时可能出现的故障。

由于验证错误，您无法保存提醒政策

您尝试保存用于监控跟踪记录数据的提醒政策，但收到类似如下所示的错误：

The following error occurred when validating your SQL Alert: Error authenticating service account `[e-mail]`. BigQuery returned an error.

此错误消息表示 Monitoring 服务账号 未被授予所需权限，或者该账号不存在。当发生某些用户发起的操作时，系统会自动创建此账号。但是，如果 Cloud Monitoring API 已停用，则系统无法创建该服务帐号。

如需解决此故障，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 API 和服务 页面，然后启用 Cloud Monitoring API：

   前往 API 和服务

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

   前往 IAM

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

3. 在 IAM 页面上，执行以下操作：

   1. 选择包括 Google 提供的角色授权 。

   2. 如果 Monitoring 服务账号未列出，请创建基于 SQL 的提醒政策，然后尝试保存该政策。

      当您保存该政策时，系统会创建 Monitoring 服务账号。由于此服务帐号没有所需的 IAM 角色，因此保存操作会失败。

   3. 向 Monitoring 服务账号授予以下角色：

      • 针对项目的 Monitoring Service Agent (roles/monitoring.notificationServiceAgent) 。
      • 针对关联的数据集的 BigQuery Data Viewer (roles/bigquery.dataViewer)
      注意 ：我们建议您将 BigQuery Data Viewer 角色 授权限制为针对跟踪记录数据的关联数据集。请勿在项目级层授予此角色。

显示“视图不存在”的错误消息

您在 Observability Analytics 页面的查询窗格中输入 SQL 查询，但 SQL 解析器显示以下错误：

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views/OBS_VIEW_ID does not exist

当找不到 FROM 语句中指定的视图时，系统会报告上述错误。

如需解决此错误，请验证您的视图是否具有正确的语法：

• 验证视图的完全限定名称是否符合 Observability Analytics 命名方案所需的语法。您可以通过显示视图的默认查询来了解视图所需的语法。

• 如果 Google Cloud 项目 ID、位置、存储桶 ID、数据集 ID 或视图 ID 包含句点字符 (.)，请验证该字段是否用单反引号 (`) 括起来。

  例如，如果您的 Google Cloud 项目的 ID 为 example.com:bluebird， 则 FROM 语句如下所示：

  FROM `example.com:bluebird`.`us`.`_Trace`.`Spans`.`_AllSpans`
  

显示“Observability Analytics 使用入门”消息

您打开 Observability Analytics 页面，该页面会显示一个窗口，其中包含类似如下所示的消息：

Get started with Observability Analytics

如需使用 Observability Analytics，请在窗口中点击 关闭。

当您没有任何已升级为使用 Observability Analytics 的日志存储分区时，系统会显示上述消息。但是，您的跟踪记录数据不会存储在日志存储桶中。

联接多个视图失败

您编写了一个联接多个视图的查询，但该查询被标记为无效。

并非所有视图都可以联接。

如需联接视图，请遵守以下限制：

1. 视图的位置满足以下条件之一：

   • 所有视图都位于同一位置。
   • 所有视图都位于 global 或 us 位置。

2. 当存储资源使用客户管理的加密密钥 (CMEK) 时， 以下条件之一必须为 true：

   • 使用 CMEK 的存储资源使用相同的 Cloud KMS 密钥。
   • 使用 CMEK 的存储资源具有共同的祖先，并且该祖先指定了一个与存储资源位于同一位置的默认 Cloud KMS 密钥。

   当一个或多个存储资源使用 CMEK 时，系统会使用共同的 Cloud KMS 密钥或祖先的 默认 Cloud KMS 密钥对联接生成的临时数据进行加密。

例如，假设您有两个视图位于同一位置。那么，当以下任一条件为 true 时，您可以联接这些视图：

• 存储资源不使用 CMEK。
• 一个存储资源使用 CMEK，另一个不使用。
• 两个存储资源都使用 CMEK，并且都使用相同的 Cloud KMS 密钥。

• 两个存储资源都使用 CMEK，但它们使用不同的密钥。不过，这些资源共享一个 祖先，该祖先指定了一个与 存储资源位于同一位置的默认 Cloud KMS 密钥。

  例如，假设日志存储桶和可观测性存储桶的资源层次结构 包含同一组织。当您为该组织配置了 Cloud Logging 和可观测性存储分区的默认资源设置，并为存储位置设置了相同的默认 Cloud KMS 密钥时，您可以联接这些存储分区中的视图。

Trace 探索器 页面中没有任何数据

您的应用正在向您的 Google Cloud 项目发送跟踪记录数据。 但是，当您打开 Trace 探索器 页面时，没有任何数据显示。

您无法查看跟踪记录数据可能有以下几个原因：

• 您未被授予查看数据所需的权限。
• 跟踪记录 span 未发送到您的项目。
• 您的应用没有写入跟踪记录数据所需的权限。
• 您的跟踪记录 span 未存储。

以下小节提供了有关如何排查所列故障场景的信息。

验证您是否有权查看跟踪记录数据

如需查看跟踪记录数据，请确保您已被授予 Cloud Trace User 角色 (roles/cloudtrace.user)。

验证跟踪记录 span 是否已发送到您的项目

如需验证 span 是否已发送到您的项目，请执行以下操作：

1. 启用 Cloud Trace 和 Telemetry API。

   启用 API 所需的角色

   如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予 角色。

   启用 API

   这两个 API 都可以注入跟踪记录 span。不过，我们建议使用 Telemetry API，因为它与 OpenTelemetry 生态系统兼容，并且其限制比 Cloud Trace API 更宽松。

   注意 ：可能存在组织政策停用了 Cloud Trace API。这些政策会阻止您启用该 API。

2. 前往已启用的 API 和服务 页面，找到 Cloud Trace API 和 Telemetry API 的行。

   如果这两个 API 的请求 计数为零，则表示没有跟踪记录数据发送到您的项目。

验证您的应用是否具有写入跟踪记录 span 所需的权限

如需确定您的应用是否有权将跟踪记录数据写入到您的项目，请执行以下操作：

1. 前往已启用的 API 和服务 页面，找到 Cloud Trace API 和 Telemetry API 的行，然后检查错误 列。

2. 如果您在任一 API 的错误 列中看到非零值，则表示通过该 API 读取或写入跟踪记录数据时出现错误。如需 确定错误类型，请选择该 API，然后选择 指标 标签页，并 查看 按 API 方法划分的错误：

   如果写入失败，请向 提供凭据的服务账号授予以下角色：

   • Cloud Trace API：Cloud Trace Agent 角色 (roles/cloudtrace.agent)。
   • Telemetry API：Cloud Telemetry Trace Writer (roles/telemetry.tracesWriter)。

验证您的跟踪记录数据是否已存储

跟踪记录 span 存储在名为 _Trace 的可观测性存储桶中。当您的 Google Cloud 项目收到跟踪记录 span 时，系统会自动预配该存储桶 。但是，在某些情况下，预配会失败。

如需确定是否存在用于存储跟踪记录数据的可观测性存储桶，您可以 选择列出可观测性存储桶，也可以 打开 Trace 探索器 页面。例如，您可以执行以下操作：

1. 在 Google Cloud 控制台中，前往 Trace 探索器 页面：

   转到 Trace 探索器

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

2. 如果您看到类似如下所示的横幅，则表示未预配跟踪记录数据的存储空间。

   Trace storage is not initialized for this project. Enable trace storage to begin collecting trace data.
   

   如需为跟踪记录数据预配可观测性存储桶，请前往该横幅，然后点击启用 。

   当您点击启用时，该操作会导致 span 发送到您的 项目。当系统收到 span 时，它会发出命令来创建名为 _Trace 的可观测性存储桶。此过程可能需要几分钟才能完成。

   初始化成功后，系统会显示通知横幅，并且 Cloud Trace 会注入过去一小时内发送的所有跟踪记录数据。 这些数据存储在临时缓冲区中。数据可能需要几分钟才能显示在 Trace 探索器 中。如果您没有看到任何数据，请刷新窗口。

3. 如果启用命令失败，则会显示以下消息：

   Initializing trace storage has failed for an unexpected reason. Please file a support ticket for assistance.
   

   如需解决此故障，请点击 提交工单，与 Google Cloud 支持团队联系。

搜索特定跟踪记录失败

您在 Trace 探索器 页面中输入跟踪记录 ID。系统找不到该跟踪记录，并显示类似如下所示的消息：

The select trace with ID abcde does not exist or is older than 30 days and has been deleted per our retention policy.

如需解决此故障，请尝试执行以下操作：

1. 验证与跟踪记录 ID 相关联的时间戳是否在保留期限内。

2. 确定存储跟踪记录的 Google Cloud 项目，并验证 控制台中的资源选择器是否选择了此项目。 Google Cloud 默认情况下，Trace 探索器 页面只能访问存储在所选项目中的跟踪记录数据。

Trace 探索器 页面中缺少旧数据

您正在使用 Trace 探索器 页面，并且可以查看最近的数据，但是当您将时间范围选择器设置为 30 天或更大的值时，系统不会显示旧数据。

Trace 探索器 页面不会显示时间段大于 Cloud Trace 数据保留期限（30 天）的数据。

如果时间范围选择器为 30 天或更短，则缺少的数据表示 Trace 探索器 页面查询的数据库的创建时间比您设置的时间范围更晚。例如，如果您将此值设置为 20 天，但只能看到最近 10 天的数据，则表示该数据库是在 10 天前创建的。此外，此数据库仅包含在该数据库创建后发送到您的 Google Cloud 项目的跟踪记录。

显示不完整的跟踪记录

您打开 Trace 探索器 页面并选择要查看的 span。 详细信息 弹出式窗口会显示跟踪记录，但该跟踪记录不完整。系统不会显示某些 span。

span 可能会因以下原因而缺失：

• Trace 探索器 页面未搜索存储跟踪记录的 span 数据的所有 Google Cloud 项目 。

• 您在存储跟踪记录的 span 数据的项目中的 IAM 角色不包含查看跟踪记录数据所需的权限。 Google Cloud

• 存在插桩问题。例如，只有跟踪记录中的部分 span 发送到了您的 Google Cloud 项目。

如需解决这些问题，请执行以下操作：

1. 在 Trace 探索器 页面中，请务必将范围 元素设置为列出存储所选跟踪记录的 span 的项目的跟踪记录范围。

   如果没有包含您在上一步中确定的项目的跟踪记录范围，请创建或修改现有跟踪记录范围。如需了解详情，请参阅 创建和管理跟踪记录范围。

2. 验证您在存储 span 数据的项目中是否具有 Cloud Trace User 角色 (roles/cloudtrace.user)。

您没有查看跟踪记录数据所需的权限

您正在查看 Trace 探索器 页面，并看到以下通知：

You don't have the required permissions to view trace data for one or more projects listed in the trace scope.

如需解决此消息，请在工具栏中执行以下操作：

1. 展开范围 元素，然后确定所选的跟踪记录范围。
2. 在优化范围 弹出式窗口中，选择管理范围 。
3. 找到您在第一步中确定的跟踪记录范围，然后展开详细信息以查看项目列表。 Google Cloud
4. 对于跟踪记录范围中的每个 Google Cloud 项目，验证您是否具有 Cloud Trace User (roles/cloudtrace.user) 角色。如果您在某个项目中没有 该角色，请让管理员或项目所有者向您 授予该角色。

不支持跨区域查询

您打开 Trace 探索器 页面，该页面会显示类似如下所示的消息：

Error loading chart data. Cross-regional queries are not supported. The selected scope comprises buckets residing in multiple locations: list of locations.

此错误消息表示 Trace 探索器 页面需要查询存储在不同位置的数据。

如需解决此故障，请执行以下操作之一：

• 将跟踪记录数据限制为由所选项目存储的数据：

  • 前往 Trace 探索器 页面的工具栏，然后展开范围 菜单。
  • 在优化范围 弹出式窗口中，选择当前项目 。

• 选择列出数据存储在同一位置的项目的跟踪记录范围。如需进行此更改，请使用范围 菜单中的选项。

• 从所选跟踪记录范围中移除数据存储位置与所选项目不同的项目：

  • 前往 Trace 探索器 页面的工具栏，然后展开范围 菜单。
  • 在优化范围 弹出式窗口中，选择管理范围 。
  • 在跟踪记录范围 页面中，您可以修改任何跟踪记录范围。

  如需查找跟踪记录数据的存储位置，请运行 List observability buckets 命令。在 路径参数中指定您的项目，对于 LOCATION，请将该字段 设置为连字符 (-)，该连字符充当通配符。

跟踪记录中缺少 span ID 消息

您的跟踪记录包含“缺少 span ID”消息。

在分布式跟踪系统中，跟踪记录不完整是正常现象。如果抽样的 span 包含对另一个尚未收到的 span 的引用，则跟踪记录不完整。未解析的引用可能是由于以下原因造成的：

• 引用的 span 未抽样。
• 引用的 span 已抽样，但 Cloud Trace 尚未收到该 span，或者 Cloud Trace 已收到该 span 但未存储。

当您查看不完整的跟踪记录时，Cloud Trace 会在跟踪记录详情窗格中显示“缺少 span ID”消息。

如果您始终看到“缺少 span ID”消息，请尝试执行以下操作：

• 对于您管理的组件，请验证它们是否遵循并 传播标头的 sampled 标志 标志（如果此 字段存在）。此设置会提示子组件对请求进行抽样。如需详细了解跟踪记录标头，请参阅 上下文传播协议。

  Google Cloud 服务通常会遵循此提示。但是，它们也会限制写入跟踪记录数据的速率。

• 如果您使用的是 Cloud Service Mesh，请验证您是否遵循了有关传播这些配置的跟踪记录上下文的指南。如需了解 Cloud Service Mesh 指南，请参阅 跟踪记录上下文传播。

无法关联日志和跟踪记录数据

您正在执行以下操作之一：

• 您正在查看跟踪记录 span，并且想要查看关联的日志条目。 但是，系统未列出任何日志数据，或者当您打开 Logs Explorer 页面时，该页面未显示任何日志条目。

• 您正在查看日志条目，并且想要查看关联的跟踪记录 span。 但是，当您使用日志条目中的选项打开 Trace 探索器 页面时，该页面未显示任何跟踪记录数据。

如需解决这些故障，请配置可观测性范围。此范围指定在打开相应的探索器页面时要使用哪些跟踪记录范围和日志范围。如需了解详情，请参阅 为多项目查询配置可观测性范围。

将 Go 应用更新为使用 OpenTelemetry 后，没有跟踪记录数据

您的应用依赖于客户端库来捕获跟踪记录，并且在将应用更新为使用 OpenTelemetry 后，您不再看到 Cloud Trace 数据。

由于某些适用于 Go 的 Cloud 客户端库与 OpenCensus 集成，因此您必须使用 OpenCensus Bridge。 如需详细了解该 Bridge 解决的问题，请参阅 OpenCensus Bridge。

如需了解适用于 Go 的 Cloud 客户端库的更新，请参阅 问题 #4237。