查找和探索轨迹

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

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

Trace 探索器页面简介

为了帮助您识别轨迹数据中的趋势和模式，系统会对延迟时间数据进行汇总，并以图表的形式显示。热图是默认的可视化图表，它使用颜色来表示单元格中的跨度数。包含多个 span 的单元格的颜色比包含少量 span 的单元格的颜色深。 您可以选择某个单元格或激活某个单元格的提示，以获取更多信息。其他可视化图表可让您查看延迟时间（以百分位表示）和跨度比率信息。 对于所有可视化图表，您都可以使用指针展开 x 轴。对于折线图，您可以展开 x 轴和 y 轴。

在调查问题时，您可能希望查看特定轨迹或仅查看具有某些属性的 span：

• 如果您知道某个轨迹的 ID，请在工具栏中依次点击网页浏览 搜索轨迹，然后在对话框中输入轨迹 ID。接下来，您可以在轨迹中搜索跨度和属性中的关键字 。

• 查看汇总数据时，您可以应用过滤条件来搜索特定时间段。例如，您可以过滤数据，以便仅显示特定服务的 span。接下来，您可以添加第二个过滤条件，将显示范围限制为报告错误的特定服务的 span。

通过表格数据，您可以查看各个 span 的详细信息，并有助于识别离群值。例如，如需查找延迟时间值最高的 span，请选择 Span 标签页，然后按延迟时间对数据进行排序。如需查找生成错误的服务，请按 span 状态过滤数据，然后选择分组标签页，该标签页会显示按 span 和服务名称汇总的数据。表格中的每一行都包含指向详细信息的链接。

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

• 搜索跟踪数据的项目。默认情况下，系统只会搜索项目选择器中选定的项目的跟踪数据。不过，您可以配置该页面，以便在跟踪记录范围内的项目列表中进行搜索。
• 您在搜索的项目中的 Identity and Access Management (IAM) 权限。 如果您无权查看某个项目的轨迹数据， Google Cloud 控制台会显示一条警告消息，并且不会显示该项目的数据。
• 时间范围设置。
• 您应用的过滤条件。

本页面的其余部分详细介绍了如何查找和探索跟踪记录数据。

准备工作

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

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

所需权限

如需使用 Google Cloud 控制台查看轨迹数据，并选择轨迹范围，您需要拥有以下权限：

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

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

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

查看汇总的跟踪记录数据

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

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

   转到 Trace 探索器

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

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

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

3. 可选：使用 Scope 元素配置要搜索哪些项目的轨迹数据：

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

   • 如需显示存储在多个项目中的跟踪数据，请展开范围元素的第一个菜单，选择跟踪范围，然后选择列出这些项目的跟踪范围。选择完毕后，“范围”菜单会显示轨迹范围图标 以及所选轨迹范围的名称。

   返回的数据取决于您在搜索的项目中所拥有的 IAM 角色。例如，如果搜索的项目包含您无权访问的 Google Cloud 项目，则系统不会返回该项目的任何跟踪记录数据。

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

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

   例如，如果您想了解延迟时间数据是否存在任何趋势，可以将此选择器设置为过去 2 周。

5. 前往工具栏，并将时间范围选择器设置为至少两周。 跨度数据存储 30 天。

6. 探索显示轨迹数据中的模式和趋势的图表：

   • 如需获取有关 span 延迟时间数据的信息，请将图表视图菜单设置为 span 时长（热图）。颜色强度与 span 的数量成正比。如需了解某个单元格的相关信息，请使用指针。提示会显示跨度数、日期和时间以及单元格的时间间隔。

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

   • 如需查看响应状态随时间变化的情况，请将图表视图菜单设置为跨度比率。该图表会显示发送到您项目的 span 的速率。

7. 探索表格数据，其中Span 标签页上列出了各个 span，Grouped 标签页上列出了按服务和名称分组的 span。

   表格中的每一行都会显示一个 span 或分组，以及指向详细信息的链接和一些指标。例如，在分组标签页上，指标包括错误率和组中的 span 数量。

   如需查找离群值，请选择列标题以对表格进行排序。

8. 添加过滤条件以限制显示哪些 span。 如需详细了解如何过滤轨迹数据，请参阅下一部分。

过滤轨迹数据

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

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

如需更改过滤条件设置，您可以使用范围过滤条件窗格或过滤条件栏。

应用跨度过滤条件

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

所有菜单的值均源自您的轨迹数据。如果某个菜单包含不含任何文字的选项，则该选项是指不包含相应属性的 span。

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

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

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

使用过滤栏

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

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

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

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

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

按应用过滤

您为应用添加的插桩生成的跟踪记录 span 可包含以下资源属性：

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

如需查找应用的轨迹数据，请在 Trace 探索器中前往范围过滤条件窗格，然后为 App Hub 应用添加过滤条件：

• 如需按应用 ID (gcp.apphub.application.id) 过滤，请使用 App Hub 应用菜单。
• 如需按应用的服务 (gcp.apphub.service.id) 进行过滤，请使用 App Hub 服务菜单。
• 如需按应用的工作负载 (gcp.apphub.workload.id) 进行过滤，请使用 App Hub 工作负载菜单。

如需了解如何对应用进行插桩，以便跟踪记录 span 包含特定于应用的属性，请参阅为应用监控进行插桩。

按 ID 查找轨迹

在排查突发事件或故障时，您可能知道轨迹 ID。如需探索该轨迹，请执行以下操作：

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

   转到 Trace 探索器

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

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

3. 前往工具栏，依次点击网页浏览 搜索轨迹，然后输入轨迹 ID。

   当您输入有效 ID 后，系统会打开详情弹出式菜单，其中显示了有关相应跟踪记录及其 span 的信息。您可以使用该窗格中的选项来探索轨迹。例如，您可以搜索跨度中的关键字。

探索轨迹

如需查看轨迹或 span，请执行以下操作：

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

   转到 Trace 探索器

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

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

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

3. 执行下列其中一项操作：

   • 前往轨迹浏览器页面的表格部分，然后从表格中选择一个条目，该表格列出了按服务和 span 名称对数据进行分组后的 span 或摘要信息。

   • 前往 Trace 探索器页面的工具栏，点击网页浏览 搜索轨迹，然后输入轨迹 ID。

   系统会打开详情弹出式菜单，并显示轨迹及其 span：

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

4. 可选：使用在轨迹中查找字段搜索轨迹中的 span 名称、服务名称和属性。

   例如，如果您输入 GET，则 span 名称、服务名称或属性窗格中显示 GET 的文本（忽略大小写）会被突出显示。

   您无法使用正则表达式进行搜索，也无法搜索日志、事件或元数据。

5. 如需查看特定 span 的详细信息，请选择相应 span，然后查看其属性和事件。如需了解详情，请参阅下一部分。

查看属性和事件

本部分介绍了如何查看标签、日志和事件。

查看标签

如需查看附加到 span 的标签，请前往属性标签页。 如需了解标签，请参阅跟踪记录标签。

查看日志和事件

如需查看与 span 相关的日志和事件，请前往日志和事件标签页。

如需查看日志条目，请点击 keyboard_arrow_down 展开。

您还可以选择查看日志按钮，该按钮会打开 Logs Explorer 页面，并将查询设置为过滤到特定轨迹、跨度和时间范围。此查询可能不会返回任何日志条目。

查看生成式 AI 事件

如需查看与生成式 AI 智能体相关的事件，请使用 GenAI 标签页。当发送到 Trace 的 span 遵循生成式 AI 系统的 OpenTelemetry 语义惯例时，此标签页会显示出来，这会导致消息名称以 gen_ai 开头。

以下屏幕截图展示了 Trace 探索器页面如何呈现生成式 AI 事件：

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

属性是描述某些特征的键值对。以下是生成式 AI 系统提供的属性示例：

• gen_ai.system：标识提供生成式 AI 功能的系统。
• gen_ai.request.model：标识请求发送到的模型。

名称以“gen_ai”开头的事件通常描述生成式 AI 系统的各个输入或输出。这些输入和输出包括系统提示和用户提示、工具输入和输出，以及模型回答。以下是生成式 AI 系统中的事件示例：

• gen_ai.system.message：一种用于记录发送给生成式 AI 模型的系统提示的事件。系统提示会向模型提供指令，这些指令通常不会显示给最终用户，但会引导模型解读用户提示。
• gen_ai.user.message：记录发送给模型的由用户提供的提示的事件。
• gen_ai.assistant.message：记录模型输出的事件，可以包含工具调用的记录，也可能包含文本回答输出。消息可能包含应用未使用的候选回答。
• gen_ai.choice：用于报告应用使用的候选输出的事件。

查看堆栈轨迹

如需查看堆栈轨迹，请使用堆栈轨迹标签页。

查看一般信息和其他元数据

如需查找有关 span 的一般信息以及指向其他 span 的链接表，请查看元数据和链接标签页。这些信息包括以下内容：

• Span ID：span ID 是一个 64 位整数（0 除外）。如需了解详情，请参阅 TraceSpan。
• 父级 span ID
• 项目 ID
• 开始时间和结束时间
• 列出指向其他 span 的链接的表格

名为 Links 的表中的每一行都列出了当前 span 与另一个 span 之间的链接。属性字段列出了关联到的 span 的键值对。轨迹字段会链接到所链接 span 的轨迹。如果此字段包含 Current trace，则关联到的 span 与当前 span 位于同一轨迹中。否则，该字段包含跟踪记录 ID。如需了解链接，请参阅 Links API 参考文档页面。

查看趋势

将更新部署到应用后，您可能需要确定更新是否影响了响应延迟时间。您可以设置时间范围选择器，以便同时显示升级前后的延迟时间数据，从而查看延迟时间数据的变化趋势。

如需查看跟踪记录数据中的趋势，请执行以下操作：

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

   转到 Trace 探索器

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

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。对于 App Hub 配置，请选择 App Hub 宿主项目或管理项目。
3. 可选：添加过滤条件以配置显示哪些 span。
4. 前往工具栏，并将时间范围选择器设置为至少两周。 跨度数据会存储 30 天。
5. 可选：更改图表视图菜单的选择。

后续步骤

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