查找和探索轨迹

如需查看跟踪记录数据的汇总表示形式，或者查找和探索包含特定标签的单个跟踪记录或跟踪记录，请使用 Trace 探索器 页面。

以下屏幕截图展示了跟踪记录数据的显示方式：

如需运行对 span 执行汇总分析的查询，请使用 Observability Analytics 页面或 BigQuery。这两个界面都支持使用 SQL 查询 span 数据。使用 Observability Analytics 页面时，您可以将查询结果显示为表格或图表。如需详细了解如何使用 SQL 查询跟踪记录数据，请参阅 查询和分析跟踪记录。

此功能仅适用于 Google Cloud 项目。 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

关于 Trace 探索器 页面

为了帮助您识别跟踪记录数据中的趋势和模式，延迟时间数据会汇总并显示在图表中。热图使用颜色来表示单元格中的 span 数量。与 span 较少的单元格相比，包含许多 span 的单元格颜色较深。每个单元格的工具提示都会显示延迟时间和其他信息。 您还可以查看延迟时间百分位数和 span 速率信息。

在调查问题时，您可能需要查看特定跟踪记录或仅查看具有特定属性的 span：

• 如需限制显示哪些 span，请应用过滤条件。例如，您可以按服务、应用、错误状态和其他属性进行过滤。

• 如需显示特定跟踪记录，请使用工具栏的 点击 pageview 搜索跟踪记录 选项。

如需识别离群值并查看各个 span 的详细信息，请使用表格部分：

• 您可以按时长标题对Span 和分组 标签页的行进行排序。

• 如需了解不同服务生成了多少 span，请使用分组 标签页。每一行都对应一个服务和 span 名称，并且每个条目都会显示延迟时间统计信息。

如需探索 span 或分组的详细信息，请从表格部分中的某一行选择相应条目。系统会打开一个弹出式窗口，在跟踪记录上下文中显示相应 span。在此视图中，您可以探索 span 及其属性，并查看事件和日志数据。您还可以在跟踪记录中搜索 span 和属性中的关键字。

Trace 探索器 页面依赖的跟踪记录数据取决于以下因素：

• 范围 设置，用于确定系统在哪些视图中搜索跟踪记录数据。页面打开时，范围 元素会设置为默认 跟踪记录范围，并且系统会查询 该范围中列出的视图以获取跟踪记录数据。

  在新项目中，默认跟踪记录范围会列出该项目的 _AllSpans。该视图提供对项目存储的所有跟踪记录数据的读取权限。

• 您在搜索的视图中的 Identity and Access Management (IAM) 权限。 如果您没有查看项目的跟踪记录数据的权限，则 控制台会显示警告消息，并且不会显示该 项目的数据。 Google Cloud

• 时间范围设置。

• 您应用的过滤条件。

本页面的其余部分提供了有关如何查找和探索跟踪记录数据的更多信息。

准备工作

如需获得使用控制台查看跟踪记录数据以及选择跟踪记录范围所需的权限，请让您的管理员为您授予项目的Cloud Trace User (roles/cloudtrace.user) IAM 角色。 Google Cloud 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含 使用 Google Cloud 控制台查看跟踪记录数据以及选择跟踪记录范围所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需使用 Google Cloud 控制台查看跟踪记录数据以及选择跟踪记录范围，您需要拥有以下权限：

• 如需选择跟踪记录范围： cloudtrace.traceScopes.[get, list]
• 如需读取默认跟踪记录范围： observability.scopes.get

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解角色，请参阅 使用 Identity and Access Management 控制访问权限。

查看汇总的跟踪记录数据

如需查看跟踪记录数据的汇总信息，请执行以下操作：

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

   转到 Trace 探索器

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

   在首次将跟踪记录数据写入 Google Cloud 项目后，可能需要几分钟的时间才能查看该数据。如果您在等待几分钟后未看到任何跟踪记录数据，则可能是您的项目没有任何数据可显示，或者存在配置问题。如需了解如何解决这些问题，请参阅 问题排查：Trace 界面中没有数据。

2. 配置 Trace 探索器 页面：

   1. 在控制台的工具栏中，选择您的项目。 Google Cloud Google Cloud 对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。

   2. 可选：使用范围 元素配置系统在哪些视图中搜索跟踪记录数据：

      • 如需显示项目存储的跟踪记录数据，请将 范围元素的第一个菜单设置为 项目或设置为 _默认。 这两个设置是等效的。

      • 如需显示多个项目存储的跟踪记录数据，请展开 范围元素的第一个菜单，选择 跟踪记录范围，然后选择列出这些项目的 _AllSpans视图的跟踪记录范围。选择后，范围菜单会显示 跟踪记录范围图标 和所选 跟踪记录范围的名称。

      系统显示的数据取决于您在搜索的视图中的 IAM 角色。例如，如果您没有查看视图中数据所需的权限，系统就不会显示该数据。

      如需了解详情，请参阅 创建和管理跟踪记录范围。

   3. 可选：使用时间范围选择器或使用指针突出显示 x 轴上的范围来更新时间范围。

      例如，如果您想查看延迟时间数据中是否存在任何趋势，可以将此选择器设置为过去 2 周 。 span 数据会存储 30 天。

3. 探索热图：

   • 使用颜色来识别趋势和离群值。与 span 较少的单元格相比，包含许多 span 的单元格颜色 较深。

   • 使用单元格的工具提示查看单元格的详细信息。工具提示会列出 span 数量、日期和时间以及单元格的时间间隔。

     **注意**： 如果您在热图中选择了一个单元格，则列出 各个 span 或 span 分组的表格会更新。

4. 探索延迟时间百分位数和错误率：

   • 如需查看延迟时间趋势，请将图表视图 菜单设置为 Span 时长（百分位数） 。 时长图表会显示第 50 百分位、第 90 百分位、第 95 百分位和第 99 百分位。

   • 如需将响应状态显示为时间的函数，请将图表视图 菜单设置为 Span 速率 。图表会显示发送到项目的 span 的速率。

5. 使用 Span 和分组 表格来识别离群值或查看统计信息。Span 表格会列出各个 span。分组 表格会按名称以及服务或工作负载名称对 span 进行分组。

   • 如需查看离群值或查找 span 名称，请对表格进行排序。您可以按任意列标题进行排序。

     例如，按时长对 Span 表格进行排序可让您找到延迟时间较高的 span。

   • 如需查看平均延迟时间等统计信息，请使用分组 表格。

   • 如需查找 App Hub 注册的服务和工作负载，请在 服务/工作负载 列中搜索包含 服务图标 或 工作负载图标 的条目。 App Hub 注册的服务或工作负载提供的链接会打开相应的应用监控信息中心。

   如果您想详细了解特定分组，请选择相应行的 span 名称。系统会打开一个弹出式窗口，在跟踪记录上下文中显示相应 span。然后，您可以探索 span 和跟踪记录。

6. 如需限制显示哪些 span，请添加过滤条件。 如需详细了解如何过滤跟踪记录数据，请参阅下一部分。

过滤跟踪记录数据

如需仅显示您感兴趣的信息，请应用过滤条件。 过滤条件会限制显示的数据。例如，您可以按服务名称和状态进行过滤。或者，如果您已将应用部署到 App Hub ，则可能需要仅查看应用的跟踪记录数据 ，或者查看属于该应用的特定服务或工作负载的跟踪记录数据 。

添加或移除过滤条件后，Trace 探索器 页面显示的数据会刷新，并且仅显示与所有应用的过滤条件匹配的 span。

按 ID 过滤跟踪记录

在排查突发事件或故障时，您可能知道跟踪记录 ID。如需探索该跟踪记录，请前往工具栏， 点击 pageview 搜索跟踪记录， 然后输入跟踪记录 ID。

输入有效 ID 后，详细信息 弹出式窗口会打开并显示有关跟踪记录及其 span 的信息。您可以使用该窗格中的选项来探索跟踪记录。例如，您可以在 span 中搜索关键字 。

**注意**： 如果您输入的跟踪记录 ID 未找到，则跟踪记录数据可能 存储在 **Trace 探索器**页面未搜索的视图中， 或者您可能没有查看跟踪记录数据的 IAM 角色。如需解决这些故障，请确定存储跟踪记录数据的项目。对于每个项目，请验证您的 IAM 角色是否允许您查看跟踪记录数据，然后确保范围 元素列出了项目的跟踪记录数据的默认视图。 如需了解详情，请参阅 配置 Trace 探索器 搜索的视图。

应用 span 过滤条件

Span 过滤条件 窗格会列出最常用的过滤条件。您可以从任何子类别中选择多个条目。添加或移除过滤条件时，过滤条件 栏也会更新。

所有菜单的值都派生自跟踪记录数据。如果菜单包含没有任何文本的选项，则该选项是指不包含相应属性的 span。

以下 Span 过滤条件 通常可用：

• OpenTelemetry 服务：按 service.name 属性过滤。
• Span 名称：span 的名称。
• Span 状态：请求状态。如需了解这些值， 请参阅 OpenTelemetry SpanStatus 文档。
• 时长：span 的时长。
• Span 种类：描述 span 之间的关系。如需了解这些值，请参阅 OpenTelemetry SpanKind 文档。
• App Hub 应用：按 gcp.apphub.application.id 资源属性过滤。
• App Hub 服务：按 gcp.apphub.service.id 资源属性过滤。
• App Hub 工作负载：按 gcp.apphub.workload.id 资源属性过滤。

如果您想按Span 过滤条件 窗格中未列出的属性进行过滤，请使用过滤条件 栏。

使用过滤条件栏

借助过滤条件 栏，您可以应用具有预定义过滤条件键和您选择的值的过滤条件，也可以同时输入键和值。

如需添加过滤条件，请选择添加过滤条件，然后执行以下操作之一：

• 选择已定义的键（例如Span 名称），然后从 二级菜单中选择一个值。

• 选择添加属性过滤条件，然后添加自定义键和值。 如果您输入自己的过滤条件键，请使用与 span 上的属性键相同的语法。

  例如，如需按主机标识符过滤，请将键设置为 host.id。 同样，如需按状态代码过滤，请将键设置为 /http/status_code。 在这种情况下，您可以将值设置为 200，这会导致 过滤条件为 /http/status_code: 200。 如需让过滤条件匹配任何值，请选择任意值 。

按应用过滤

如需查找或查看您的 App Hub 注册的服务和 工作负载生成的 span，您的 span 必须包含以下资源属性：

• gcp.apphub.application.{container,id,location}
• gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

之前的资源属性由您添加到应用的插桩生成。您可以按任何资源属性过滤跟踪记录数据。 不过，以下 Span 过滤条件 会按应用、服务和工作负载 ID 进行过滤：

• App Hub 应用
• App Hub 服务
• App Hub 工作负载

如需为 App Hub 注册的服务和工作负载打开应用监控信息中心，请执行以下操作：

1. 前往 Span 或分组 表格，然后找到相应服务或工作负载。您可以查找服务图标 、 工作负载图标 ，或过滤表格。

2. 选择服务/工作负载 列中的链接。

探索跟踪记录

本部分介绍了如何在跟踪记录上下文中探索 span：

1. 打开并配置 Trace 探索器 页面。如需了解这些步骤，请参阅查看汇总的跟踪记录数据。

2. 如需查看 span 或跟踪记录的详细信息，请执行以下操作之一：

   • 前往 Trace 探索器 页面的表格部分，然后从表格部分中选择一个条目。您可以按任意表标题对表格的行进行排序。您可以应用过滤条件来 限制表格显示的 span。

   • 前往 Trace 探索器 页面的工具栏， 点击 pageview 搜索跟踪记录， 然后输入 跟踪记录 ID。

   详细信息 弹出式窗口会打开并显示跟踪记录及其 span。

   

   系统会显示您选择的 span 或跟踪记录的详细信息：

   • 名称 列会显示调用层次结构，并且第一个条目包含跟踪记录 ID。此列还可能包含注释，指明生成式 AI 事件或日志数据是否可用。
   • 服务/工作负载 列会显示服务或工作负载名称。如果设置了 OpenTelemetry 属性 service.name，系统会从中提取服务名称。 如果未设置该属性，并且服务正在 App Engine 上运行，系统会显示 App Engine 服务名称。否则，系统不会指定任何服务。
   • 延迟时间条的长度表示延迟时间值。
   • 延迟时间条的颜色表示状态。蓝色延迟时间条表示成功完成，而红色延迟时间条表示发生了错误。
   • 延迟时间条上的圆圈表示日志条目或事件与 span 相关联。如需更改此行为，请使用日志和事件 菜单。

3. 如需探索跟踪记录，请执行以下操作：

   • 使用指针选择不同的 span。选择 span 后，页面上的 标签页会刷新，以显示 span 的 属性、日志条目和事件。

   • 如需在跟踪记录中搜索 span 中的关键字，请使用在跟踪记录中查找 字段。

     搜索仅适用于 span 名称、服务或工作负载名称以及属性字段。 您只能按纯文本搜索，而不能搜索日志、事件或元数据。

     例如，如果您输入 GET，则系统会突出显示 名称、 服务/工作负载 和 属性 窗格中显示 GET 的文本（ 忽略大小写）。

查看属性、日志条目和事件

span 的详细信息 弹出式窗口包含以下每个标签页：

• 属性：此标签页会列出附加到 span 的标签。 如需了解标签，请参阅跟踪记录标签。

• 日志和事件 ：此标签页会列出 trace_id 和 span_id 字段与所选 span 匹配的事件和日志条目。系统只会显示您有权查看的日志条目。

  如需探索此标签页上的条目， 请点击 显示更多。

  如果您更喜欢使用 Logs Explorer 页面查看日志数据，请点击查看日志 。查询设置为过滤到特定跟踪记录、span 和时间范围。

  **注意**： 生成式 AI 事件显示在**输入/输出** 标签页上。如需了解详情，请参阅查看生成式 AI 事件。

• 堆栈轨迹：列出可用的堆栈轨迹。

• 元数据和链接 ：列出有关 span 的一般信息：

  • Span ID：span ID 是一个 64 位整数（0 除外）。如需了解详情，请参阅 TraceSpan。
  • 父级 span ID。
  • 项目 ID。
  • 开始时间和结束时间。

  • 列出指向其他 span 的链接的表格。对于每个链接，此表格会列出以下内容：

    • 链接到的 span 的键值对。
    • 链接到的 span 的跟踪记录 ID。如果此字段列出了 当前跟踪记录 ，则表示 span 链接到 同一跟踪记录中的另一个 span。

    如需了解链接，请参阅 Links API 参考文档页面。

详细信息 还可能包含一个名为输入/输出 的标签页。此标签页会显示生成式 AI 事件。

查看生成式 AI 事件

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅 发布阶段说明。

如需查看与生成式 AI 代理相关的事件，请使用输入/输出 标签页。此标签页会显示遵循 OpenTelemetry GenAI 语义惯例的事件。

支持两种配置：

• 基于文本的提示和回答，作为 属性附加到 span，这些属性是描述某些 特征或事件的键值对。例如，键 gen_ai.system 的值用于标识提供生成式 AI 功能的系统。生成式 AI 属性的键以 gen_ai 开头。

• 存储在 Cloud Storage 存储桶中的多模态提示和回答。Cloud Trace 通过关联跟踪记录和日志数据来识别这些事件。如需了解受支持的 配置，请参阅 收集和查看多模态提示和回答。

以下屏幕截图展示了 Trace 探索器 页面如何呈现附加到 span 的基于文本的生成式 AI 事件：

如需了解生成上一个屏幕截图的示例应用， 请参阅 使用 OpenTelemetry 对 LangGraph ReAct 智能体进行插桩。

查看对远程 MCP 服务器的调用

如需查看 MCP 服务器写入的 span，请按 span 名称过滤跟踪记录数据。例如，某些远程 Google Cloud MCP 服务器在收到 tools/call 操作时可以生成跟踪记录 span。这些 span 具有以下命名惯例：

tools/call NAME

在上面的表达式中，NAME 是指调用的端点。 例如，这可能类似于 list_keys。此命名 惯例由 OpenTelemetry Semantic Conventions for MCP 定义。

如需查找这些 span，请 [使用过滤条件栏][filter-trace] 并为 mcp.method.name 添加属性过滤条件。将过滤条件的值设置为 tools/call。

如需了解哪些远程 Google Cloud MCP 服务器支持跟踪记录生成，以及如何配置应用以指示这些服务器生成 span，请参阅使用 Trace 调查 MCP 调用。

后续步骤

• 创建和管理跟踪记录范围
• 共享跟踪记录和 span
• 问题排查