查找和浏览轨迹

如需查看跟踪数据的汇总表示形式,或查找和浏览单个跟踪记录或包含特定标签的跟踪记录,请使用轨迹浏览器页面。

只有 Google Cloud 项目支持此功能。

Trace 探索器页面简介

为了帮助您发现轨迹数据中的趋势和模式,系统会汇总延迟时间数据并将其显示在图表中。热图是默认的可视化图表,它使用颜色来表示单元格中的跨度数。与包含少量跨度的单元格相比,包含多个跨度的单元格显示的颜色较深。您可以选择单元格或激活单元格的提示,以获取更多信息。通过其他可视化图表,您可以将延迟时间视为百分位数和跨度率信息。对于所有可视化图表,您都可以使用指针展开 X 轴。对于折线图,您可以展开 x 轴和 y 轴。

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

  • 知道跟踪记录的 ID 后,在工具栏中依次点击 Search for trace(搜索跟踪记录),然后在对话框中输入跟踪记录 ID。接下来,您可以在轨迹中搜索关键字的 span 和属性

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

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

轨迹浏览器页面显示的轨迹数据取决于以下因素:

  • 搜索跟踪记录数据的项目。默认情况下,系统只会搜索项目选择器所选项目中的轨迹数据。不过,您可以将该页面配置为搜索跟踪记录范围中的项目列表。
  • 您对搜索到的项目的 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 项目。

  3. 可选:使用 Scope 元素配置要搜索哪些项目以查找轨迹数据

    • 如需显示存储在项目中的轨迹数据,请将 Scope 元素的第一个菜单设置为 Project _Default。这两种设置是等效的。

    • 如需显示存储在多个项目中的轨迹数据,请展开 Scope 元素的第一个菜单,选择 Trace scope,然后选择列出这些项目的轨迹范围。进行选择后,范围菜单会显示跟踪范围图标 和所选跟踪范围的名称。

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

    如需了解详情,请参阅创建和管理轨迹范围

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

  5. 探索图表,查看轨迹数据中的模式和趋势:

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

    • 如需查看延迟时间趋势,请将图表视图菜单设置为时长范围(百分位数)。“时长”图表会显示第 50、第 90、第 95 和第 99 百分位。

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

  6. Spans(跨度)标签页上,浏览列出了各个跨度的表格数据;在 Grouped(分组)标签页上,浏览按服务和名称分组的跨度数据。

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

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

  7. 添加过滤条件以限制显示哪些 span。例如,您可以按服务名称和状态进行过滤。当您添加或移除过滤条件时,Trace 探索器页面会刷新显示的数据,并且只会显示与所有已应用的过滤条件匹配的跨度。

    如需更改过滤条件设置,请执行以下任一操作:

    • 前往跨度过滤条件窗格,然后选择要应用的过滤条件。

      “跨度过滤条件”窗格仅列出最常见的过滤条件。如果您想按未列出的属性进行过滤,请使用过滤栏。

    • 如需使用过滤条件栏添加过滤条件,请选择添加过滤条件,然后在对话框中填写信息。

      如需按选项菜单中未列出的属性过滤,请选择添加属性过滤条件,然后添加自定义键和值。例如,如果您将键设置为 /http/status_code 并将值设置为 200,则过滤条件为 /http/status_code: 200。若要让过滤条件与任何值匹配,请选择任何值

按 ID 查找轨迹

在排查突发事件或故障时,您可能知道轨迹 ID。如需浏览该轨迹,请执行以下操作:

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

    转到 Trace 探索器

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

  2. 在 Google Cloud 控制台的工具栏中,选择您的 Google Cloud 项目。
  3. 前往工具栏,依次点击 Search for trace(搜索轨迹),然后输入轨迹 ID

    输入有效 ID 后,系统会打开详细信息弹出式窗口,并显示跟踪记录及其 span 的相关信息。您可以使用该窗格中的选项来浏览轨迹。例如,您可以按关键字搜索这些片段

浏览轨迹

如需查看轨迹或 span,请执行以下操作:

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

    转到 Trace 探索器

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

    将第一个跟踪数据写入 Google Cloud 项目后,可能需要几分钟时间才能查看这些数据。如果您在等待几分钟后没有看到任何轨迹数据,则说明您的项目可能没有任何数据可显示,或者存在配置问题。如需了解如何解决这些问题,请参阅问题排查:跟踪记录界面中没有数据

  2. 在 Google Cloud 控制台的工具栏中,选择您的 Google Cloud 项目。

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

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

    • 前往 Trace 探索器页面的工具栏,依次点击 Search for trace(搜索轨迹),然后输入轨迹 ID

    详细信息弹出式窗格随即会打开,并显示跟踪记录及其 span:

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

    例如,如果您输入 GET,系统会突出显示 span 名称、服务名称或显示 GET属性窗格中的文本(不区分大小写)。

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

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

查看属性和事件

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

查看标签

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

查看日志和事件

如需查看与该 span 相关的日志和事件,请前往日志和事件标签页。如需了解事件注解,请参阅为轨迹 span 添加注解

如需查看日志条目,请点击 展开

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

查看生成式 AI 事件

如需查看与生成式 AI 代理相关的事件,请使用 GenAI 标签页。如果发送到 Trace 的 span 遵循 适用于生成式 AI 系统的 OpenTelemetry 语义惯例,则此标签页可用,这会导致消息名称以 gen_ai 开头。

属性是用于描述某些特征的键值对。以下是生成式 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 ID:span ID 是一个 64 位整数(0 除外)。如需了解详情,请参阅 TraceSpan
  • 父级 span ID
  • 项目 ID
  • 开始时间和结束时间
  • 列出指向其他跨度的链接的表格

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

后续步骤