排查问题

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

本文档介绍了如何在使用Trace 探索器页面或旧版 Trace 探索器页面时排查问题：

• 排查 Trace 探索器页面问题
• 排查旧版 Trace 探索器页面问题

已知问题

轨迹浏览器页面存在两个已知问题：

• 在 2025 年 1 月 11 日之前写入您的 Google Cloud 项目的跨度可能无法使用。这些跨度可在旧版轨迹浏览器页面中找到。

• 在 2025 年 1 月 11 日之前写入 Google Cloud 项目的跨度对应的事件详情窗格与在该日期之后写入的跨度对应的事件详情窗格可能有所不同。

排查 Trace 探索器页面问题

本部分介绍了如何排查使用 Trace Explorer 页面时遇到的问题。

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

您使用的是 Trace Explorer 页面，但在预期跟踪记录数据存在时无法在 Google Cloud 项目中查看任何跟踪记录。

请尝试按照以下步骤操作：

1. 验证是否已启用 Cloud Trace API 以及是否有数据写入到您的项目：

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

      前往已启用的 API 和服务

   2. 如果列出了 Cloud Trace API，请继续执行下一步。否则，请启用此 API。

      如需启用该 API，请点击启用 API 和服务，搜索“Cloud Trace API”，选择该选项，然后点击启用。

      注意 ：组织可能已实施一些政策来停用 Cloud Trace API。这些政策会阻止您启用该 API。

2. 在启用 API 和服务页面上，找到标记为 Cloud Trace API 的行。

3. 如果标记为请求的列未列出任何数值信息，则表示没有跟踪记录数据发送到您的 Google Cloud 项目。

   如需解决此支持请求，请检查您的应用和代理，确保它们已配置为将跟踪记录发送到正确的项目。

4. 如果标记为“错误”的列列出了非零值，则表示读取或写入轨迹数据时出现了错误。如需详细了解错误的来源，请依次选择 Cloud Trace API 和 Metrics（指标）标签页，然后找到标签为 Errors by API method（按 API 方法划分的错误数）的图表：

   • 如果写入失败，请向提供身份验证凭据的服务账号授予 Cloud Trace Agent 角色 (roles/cloudtrace.agent)。此角色包含 cloudtrace.traces.patch 权限，可让应用将跨度数据写入 Google Cloud 项目。

     如需了解详情，请参阅 Cloud Trace IAM 角色。

   • 如果读取失败，请确保您在 Google Cloud 项目中的 IAM 角色包含 Cloud Trace User 角色 (roles/cloutrace.user) 中的权限。如需查看此角色的权限列表，请参阅 Cloud Trace IAM 角色。

5. 验证 Trace 探索器页面是否正在当前项目中搜索跟踪记录数据：

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

      转到 Trace 探索器

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

   2. 在工具栏中，前往范围元素，展开优化范围菜单，选择当前项目，然后选择应用。

6. 请尝试下列操作之一：

   • 切换到旧版 Trace 探索器页面。此页面从与跟踪记录浏览器页面不同的数据库中读取跟踪记录和跨度数据。

     前往旧版轨迹探索器

   • 使用 Cloud Trace API 将 span 发送到您的 Google Cloud 项目。如需了解详情，请参阅强制为 Trace Explorer 页面创建数据库。

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

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

Trace Explorer 页面不会显示超过 Cloud Trace 数据保留期限（30 天）的时间段的数据。

如果时间范围选择器的值不超过 30 天，则缺失的数据表示 Trace Explorer 页面查询所查询的数据库的创建时间晚于您的时间范围设置。例如，如果您将此值设置为 20 天，并且您只能看到最近 10 天的数据，则表示数据库是在过去 10 天内创建的。此外，此数据库仅包含在数据库创建后发送到您的 Google Cloud 项目的轨迹。

如需查看和分析较早的跟踪记录数据，请切换到旧版 跟踪记录浏览器页面。此页面从与跟踪记录浏览器页面不同的数据库中读取跟踪记录和跨度数据。

前往旧版轨迹探索器

轨迹中缺少跨度

您打开 Trace 探索器页面，然后选择要查看的跨度。详情弹出式窗口会显示轨迹，但其中缺少一些 span。

span 可能缺失的原因如下：

• Trace Explorer 页面不会搜索存储跟踪记录的跨度数据的所有 Google Cloud 项目。

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

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

• 这些数据已在 2025 年 1 月 11 日之前写入您的 Google Cloud 项目。

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

1. 在旧版 Trace 探索器页面中确定跟踪是否已完成：

   1. 在轨迹的详情动作条中，将轨迹 ID 复制到剪贴板。

   2. 前往旧版 Trace 探索器页面：

      前往旧版轨迹探索器

   3. 将轨迹 ID 粘贴到轨迹 ID 字段中。

      Trace 详情页面会更新，并列出存储跟踪记录 span 的项目。

2. 如果旧版 Trace 探索器页面中显示跟踪记录已完成，请返回 Trace 探索器页面，并将范围元素设置为列出您在上一步中标识的所有项目的跟踪记录范围。这些项目存储着所选轨迹的 span。

   如果没有包含您在上一步中标识的项目的轨迹范围，请创建或修改现有轨迹范围。如需了解详情，请参阅创建和管理轨迹范围。

3. 如果旧版 Trace 探索器页面中显示的跟踪记录不完整，则表示系统未记录任何跨度，或者您在存储跨度数据的项目中没有 Cloud Trace 用户角色 (roles/cloudtrace.user)。

您无权查看轨迹数据

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

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

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

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

强制为轨迹浏览器页面创建数据库

如果项目中唯一的跟踪数据来自 Google Cloud 为 Cloud Trace 预配置的服务，Trace 探索器页面可能不会为您的跟踪记录和跨度数据创建数据库。不过，您可以使用 Cloud Trace API 向 Google Cloud 项目发送轨迹，以强制创建此数据库。

例如，您可以执行以下操作：

1. 前往 patchTraces 文档页面。

2. 在试用此方法窗格中，执行以下操作：

   1. 在 projectId 字段中，输入您的 PROJECT_ID。

   2. 将用于定义包含单个跨度的轨迹的 JSON 复制到剪贴板，然后将其粘贴到请求正文字段中。

      在复制 JSON 之前，请执行以下操作：

      • 将 PROJECT_ID 替换为您的项目 ID。

      • 将 END_TIME 替换为当前时间，并将 START_TIME 替换为早于结束时间的值。如果您使用的是 Linux，请运行 date -Isec 以获取正确格式的当前时间。例如，您可以按如下方式设置这些字段：

        "startTime": "2024-05-31T15:10:35.398448Z",
        "endTime": "2024-05-31T15:10:35.574999047Z",
        

      • 每次执行该命令时，更新 traceId 和 spanId 字段。

        "traces": [
          {
            "projectId": "PROJECT_ID",
            "traceId": "33fc0d8c45bb4e5cebb29f047931270d",
            "spans": [
              {
                "spanId": "17941747227541407973",
                "name": "/",
                "startTime": "START_TIME",
                "endTime": "END_TIME",
              }
            ]
          }
        ]
        

   3. 按执行。

      命令成功完成后，响应正文为空。如果您前往 Trace Explorer，则可以查看轨迹。轨迹可能要稍微延迟一些时间才会显示在 Google Cloud 控制台中。

排查旧版 Trace 探索器页面问题

本部分介绍了如何排查使用旧版 轨迹浏览器页面时遇到的问题。

旧版界面中没有任何数据

您使用的是旧版 Trace Explorer 页面，并且在预期跟踪记录数据存在时无法在 Google Cloud 项目中查看任何跟踪记录。

如需解决此失败问题，请尝试以下步骤：

1. Enable the Cloud Trace API.

   Enable the API

   注意： 组织可能已实施一些政策来停用 Cloud Trace API。这些政策会阻止您启用该 API。

2. 在 Google Cloud 控制台中，前往 API 和服务页面：

   前往 API 和服务

   找到标记为 Cloud Trace API 的行后，请尝试执行以下操作：

   • 如果标记为请求的列未列出任何数值信息，则表示没有跟踪记录数据发送到您的 Google Cloud 项目。

     如需解决此支持请求，请检查您的应用和代理，确保它们已配置为将跟踪记录发送到正确的项目。

   • 选择 Cloud Trace API，选择 Metrics（指标）标签页，然后找到标签为错误（按 API 方法）的图表：

     • 如果写入失败，请为提供身份验证凭据的服务账号授予 Cloud Trace Agent (roles/cloudtrace.agent) 角色。此角色包含 cloudtrace.traces.patch 权限，可让应用将跨度数据写入 Google Cloud 项目。

       如需了解详情，请参阅 Cloud Trace IAM 角色。

     • 如果读取失败，请确保您在 Google Cloud 项目中的 IAM 角色包含 Cloud Trace User (roles/cloutrace.user) 角色中的权限。如需查看此角色的权限列表，请参阅 Cloud Trace IAM 角色。

旧版界面中没有已部署应用的轨迹数据

您已部署一款应用，该应用使用 Cloud Trace API 将数据发送到您的 Google Cloud 项目，但系统未收集跟踪记录数据。

请尝试以下操作：

• 如果您在 Google Cloud 控制台的旧版 Trace 探索器页面中没有看到任何数据，请按照标题为旧版 Trace 界面中没有任何数据的部分中的步骤操作。

• 如果应用未部署在 Google Cloud 上，或者它使用服务账号提供身份验证凭据，请确保已向该服务账号授予 Cloud Trace Agent 角色 (roles/cloudtrace.agent)。 Google Cloud

  此角色包含 cloudtrace.traces.patch 权限，可让应用将跨度数据写入 Google Cloud 项目。

• 如果应用依赖于 OpenTelemetry，请执行以下操作：

  • 对于根服务，请尝试更新环境变量，以便 OpenTelemetry 使用采样率为 0.5 的 traceidratio 采样器：

    export OTEL_TRACES_SAMPLER="traceidratio"
    export OTEL_TRACES_SAMPLER_ARG="0.5"
    

  • 对于所有其他服务，请不设置 OTEL_TRACES_SAMPLER 环境变量，以使用默认采样器 parentbased_always_on。默认设置表示 span 的采样决策会从其父 span（如果存在）继承。如果父级跨度不存在，则系统会对该跨度进行采样。

  除非您的应用始终对每个跨度进行采样，否则通常无法强制对请求进行端到端跟踪，因为端到端请求中的每个组件都会做出自己的采样决策。不过，您可以通过向轨迹标头添加 sampled 标志（并将此标志设置为 true）来影响此决定。此设置是对子组件进行请求抽样的提示。如需详细了解跟踪标头，请参阅用于上下文传播的协议。

轨迹中缺少 span ID 消息

您的轨迹包含“缺少 span ID”消息。

在分布式跟踪系统中，不完整的轨迹是正常现象。如果采样的 span 包含对未收到的其他 span 的引用，则轨迹不完整。出现未解析的引用的原因可能如下：

• 未对引用的跨度进行抽样。
• 引用的 span 已被抽样，但尚未被 Cloud Trace 收到，或者 span 已收到，但未存储。

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

如果您一直看到“缺少 span ID”消息，请尝试以下操作：

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

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

• 如果您使用的是 Cloud Service Mesh，请确保遵循有关为这些配置传播轨迹上下文的指导。如需 Cloud Service Mesh 指南，请参阅跟踪上下文传播。

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

您的应用依赖于客户端库来捕获轨迹，但在将应用更新为使用 OpenTelemetry 后，您不再看到 Cloud Trace 数据。

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

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