排查问题

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

已知问题

本部分列出了已知问题：

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

排查 Log Analytics 问题

本部分介绍了如何解决在使用 Log Analytics 查询轨迹数据时可能遇到的故障。

表明视图不存在的错误消息

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

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

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

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

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

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

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

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

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

您有一个应用，正在将跟踪记录数据发送到您的 Google Cloud 项目。不过，当您打开 Trace 探索器页面时，系统不会显示任何数据。

您无法查看轨迹数据的原因可能有多种：

  • 您未获得查看数据所需的权限。
  • 跟踪范围未发送到您的项目。
  • 您的应用没有写入轨迹数据所需的权限。
  • 系统不会存储您的轨迹跨度。

以下各子部分提供了有关如何排查所列故障情形的信息。

验证您是否有权查看轨迹数据

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

验证是否已将轨迹跨度发送到您的项目

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

  1. Enable the Cloud Trace and Telemetry APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    这两个 API 都可以接收轨迹 span。不过，建议使用 Telemetry API，因为它与 OpenTelemetry 生态系统兼容，并且其限制比 Cloud Trace API 更宽松。

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

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

验证您的应用是否拥有写入轨迹 span 所需的权限

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

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

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

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

验证您的轨迹数据是否已存储

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

如需确定是否存在用于存储跟踪记录数据的可观测性存储桶，您可以 [列出可观测性存储桶][trace-storage-list-buckets]，也可以打开 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 会提取过去一小时内发送的所有轨迹数据。此数据存储在临时缓冲区中。数据可能需要几分钟时间才会显示在轨迹浏览器中。如果您没有看到任何数据，请刷新窗口。

  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。 详细信息弹出式菜单会显示轨迹，但轨迹不完整。部分跨度未显示。

轨迹可能因以下原因而缺失：

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

  • 您在存储相应轨迹的 span 数据的 Google Cloud 项目中的 IAM 角色不包含查看轨迹数据所需的权限。

  • 存在插桩问题。例如，只有轨迹中的部分 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) 角色。如果您在某个项目中没有该角色，请让管理员或项目所有者为您授予该角色。

跟踪记录中缺少 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 指南，请参阅跟踪记录上下文传播。

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

您正在执行以下某项操作：

  • 您正在查看跟踪记录范围，并希望查看关联的日志条目。 但是，系统要么未列出任何日志数据，要么在您打开 Logs Explorer 页面时未显示任何日志条目。

  • 您正在查看某个日志条目，并希望查看关联的跟踪记录范围。 不过，当您使用日志条目中的选项打开 Trace 探索器页面时，该页面不会显示任何跟踪记录数据。

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

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

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

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

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