排查问题

本页面包含 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`

显示“开始使用 Log Analytics”消息

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

Get started with Log Analytics

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

如果您没有任何 升级为使用 Log 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. 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 项目收到跟踪记录 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 探索器 页面的工具栏，然后 展开 范围 菜单。
    • 在优化范围 弹出式窗口中，选择管理范围 。
    • 在 Trace 范围 页面中，您可以修改任何跟踪记录范围。

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

跟踪记录中缺少 span ID 消息

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

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

  • 引用的 span 未抽样。
  • 引用的 span 已抽样，但 Cloud Trace 尚未收到该 span 或者该 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。