查询和分析轨迹

预览

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

本文档介绍了如何使用 Observability Analytics 查询和分析跟踪记录数据，该工具提供基于 SQL的查询界面。借助 SQL，您可以执行聚合分析，这有助于您生成分析洞见并发现趋势。如需查看查询结果，请使用表格或图表。 您还可以将这些表格和图表保存到自定义信息中心。

如果您想查看或探索单个跟踪记录或 span，或者查看附加到 span 的属性，请使用 Trace 探索器 页面。如需了解该页面的相关信息，请参阅 查找和探索跟踪记录。

对于跟踪记录，您可以查询名为 _Trace 的 Observability 存储桶。有一个视图 _AllSpans 可供查询。如需详细了解 跟踪记录数据的存储方式，请参阅 存储概览。

关联的 BigQuery 数据集简介

您不需要关联的 BigQuery 数据集即可查询跟踪记录数据，也不需要关联的数据集即可查询跟踪记录和日志数据。对于这些场景，您可以使用 Observability Analytics 页面。如需了解如何查询日志数据，请参阅 使用 Observability Analytics 查询和分析日志。

如果您要执行以下任何操作，则需要关联的 BigQuery 数据集：

• 将跟踪记录数据与其他 BigQuery 数据集联接。
• 查询来自其他服务（例如 BigQuery Studio 页面或 Looker Studio）的跟踪记录数据。
• 通过在 BigQuery 预留槽 上运行查询，提高从 Observability Analytics 运行的查询的性能。

本文档未介绍如何创建关联的数据集，也未介绍如何配置 Observability Analytics 以在预留槽上运行查询。 如需了解这些主题，请参阅 查询关联的 BigQuery 数据集。

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手， 请创建一个账号来评估我们的产品在 实际场景中的表现。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

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 API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

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 API

1. 如需获得加载 Observability Analytics 页面、编写、运行和保存跟踪记录数据的私有查询所需的权限，请让管理员为您授予以下 IAM 角色：

   • Observability View Accessor (roles/observability.viewAccessor)，用于您要查询的 Observability 视图。此角色支持 IAM Conditions，可让您将授予的权限限制为仅针对特定视图。如果您未为此角色授予附加条件，则正文可以访问所有可观测性视图。
   • Observability Analytics User (roles/observability.analyticsUser) ，用于您的项目。此角色包含保存和运行私有查询以及运行共享查询所需的权限。
   • Logs Viewer (roles/logging.viewer)用于您的项目。

   如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

   您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

显示架构

架构定义了数据的存储方式，包括字段及其数据类型。此信息对您非常重要，因为架构决定了您查询的字段以及是否需要将字段转换为不同的数据类型。例如，如需编写用于计算 HTTP 请求平均延迟时间的查询，您需要了解如何访问延迟时间字段，以及该字段是 存储为整数（如 100）还是存储为字符串（如 "100"）。如果延迟时间数据以字符串形式存储，则查询必须先将值转换为数值，然后才能计算平均值。

如需确定架构，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

   转到 Log Analytics

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

2. 在 视图 菜单中，前往 跟踪记录 部分， 然后选择 _Trace.Spans._AllSpans。

   架构 窗格会进行更新。当数据类型为 JSON 时，Observability Analytics 会自动推理列的字段。 如需查看这些推理字段在您的数据中出现的频率， 请点击 选项 ，然后 选择 查看信息和说明。

   如需了解架构，请参阅 跟踪记录数据的存储架构。

   如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则您的 Google Cloud 项目不包含名为 _Trace 的 Observability 存储桶。如需了解如何解决此失败问题，请参阅 跟踪记录存储初始化失败。

查询跟踪记录数据

本部分介绍了可用于查询跟踪记录数据的方法：

• 加载系统定义的查询，修改此查询，然后运行该查询。
• 输入并运行自定义查询。例如，您可以粘贴已有的查询或编写一个查询。自定义查询可以包含联接、嵌套查询和其他复杂的 SQL 语句。如需查看示例，请参阅示例 SQL 查询。
• 通过进行菜单选择来构建查询，然后运行该查询。 Observability Analytics 会将您的选择转换为 SQL 查询，您可以查看和修改该查询。

加载、修改和运行系统定义的查询

1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

   转到 Log Analytics

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

   注意 ：如果 可观测性分析 页面上的窗口显示“开始使用可观测性分析”消息，请在该窗口中点击 关闭。

2. 在 视图 菜单中，前往 跟踪记录 部分， 然后选择 _Trace.Spans._AllSpans。

   如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则您的 Google Cloud 项目不包含名为 _Trace 的 Observability 存储桶。如需了解如何解决此失败问题，请参阅 跟踪记录存储初始化失败。

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

   • 如需加载依赖于查询构建器 的系统定义查询，该构建器 可让您通过菜单选择来定义查询，请确保 查询 窗格显示查询构建器 。如果显示 SQL 编辑器，请 点击  构建器。

   • 如需加载提取 JSON 值的系统定义查询，请确保查询 窗格显示 SQL 编辑器。如果此窗格显示 查询构建器，请点击  SQL。

4. 在架构 窗格中，选择查询 ，然后点击覆盖 。

   查询 窗格会显示系统定义的查询。如果您选择了 查询构建器 模式，但想查看 SQL 查询，请点击  SQL。

5. 可选：修改查询。

6. 如需运行查询，请前往工具栏并选择运行查询 。

   Observability Analytics 会在表格中显示查询结果。不过，您可以创建 图表，也可以将表格或图表保存到 自定义信息中心。如需了解详情，请参阅 绘制 SQL 查询结果图表。

   如果工具栏显示在 BigQuery 中运行，则需要将 Observability Analytics 切换为使用默认查询引擎。如需进行此更改，请在 查询窗格的工具栏中，点击 设置 ，然后选择 Analytics（默认）。

输入并运行自定义查询

如需输入 SQL 查询，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

   转到 Log Analytics

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

   注意 ：如果 可观测性分析 页面上的窗口显示“开始使用可观测性分析”消息，请在该窗口中点击 关闭。

2. 在查询 窗格中，点击 SQL。

   • 如需指定时间范围，我们建议您使用时间范围选择器。如果您添加指定 timestamp 字段的 WHERE 子句，则该值会替换时间范围选择器中的设置，并且该选择器会被停用。

   • 如需查看示例，请参阅示例 SQL 查询。

   • SQL 编辑器会显示 _Trace.Spans._AllSpans 视图的完全限定名称，其格式如下：

     FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
     

     上面表达式中的字段含义如下：

     • PROJECT_ID：项目的标识符。
     • LOCATION：Observability 存储桶的位置。

     如果查询窗格显示引用 FROM 语句的错误消息，则表示找不到该视图。 如需了解如何解决此失败问题，请参阅 显示视图不存在的错误消息。

3. 如需运行查询，请前往工具栏并选择运行查询 。

   Observability Analytics 会在表格中显示查询结果。不过，您可以创建 图表，也可以将表格或图表保存到 自定义信息中心。如需了解详情，请参阅 绘制 SQL 查询结果图表。

   如果工具栏显示在 BigQuery 中运行，则需要将 Observability Analytics 切换为使用默认查询引擎。如需进行此更改，请在 查询窗格的工具栏中，点击 设置 ，然后选择 Analytics（默认）。

构建、修改和运行查询

借助查询构建器 界面，您可以通过从菜单中进行选择来构建查询。Observability Analytics 会将您的选择转换为 SQL 查询，您可以查看和修改该查询。例如，您可以先使用查询构建器 界面，然后切换到 SQL 编辑器来优化查询。

Observability Analytics 始终可以将您在查询构建器 界面中的菜单选择转换为 SQL 查询。不过，并非所有 SQL 查询都可以通过查询构建器 界面表示。例如，包含联接的查询无法通过此界面表示。

注意： 在某些情况下，您要查询的字段可能不会列出 在查询构建器界面中。当列的数据类型为 JSON 时，Observability Analytics 会自动推理列的字段。如果您希望查询使用未自动推理的 JSON 字段，请切换到 SQL 编辑器并编写查询。

如需构建查询，请执行以下操作：

1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：

   转到 Log Analytics

   如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。

   注意 ：如果 可观测性分析 页面上的窗口显示“开始使用可观测性分析”消息，请在该窗口中点击 关闭。

2. 如果 查询 窗格显示 SQL 编辑器，请选择 构建器，这将打开 查询构建器 窗格。

3. 使用来源 菜单选择要查询的视图。您的选择会映射到 SQL 查询中的 FROM 子句。

4. 可选：使用以下菜单来限制结果表或设置其格式：

   • 搜索所有字段：搜索匹配的字符串。您的选择会映射到 SQL 查询中的 WHERE 子句。

   • 列：选择结果表中显示的列。您的选择会映射到 SQL 查询中的 SELECT 子句。

     当您在此菜单中选择字段名称时，系统会打开一个对话框。在此对话框中，您可以执行以下操作：

     • 使用菜单聚合或分组数据。

       为防止出现语法错误，您对一列应用的任何汇总和分组也会自动应用于其他列。如需查看如何聚合和分组条目的示例，请参阅 使用查询构建器分组和聚合数据。

     • 将任何类型的值转换为其他指定的数据类型。如需了解详情，请参阅 CAST 文档。

     • 使用正则表达式提取值的子字符串。如需了解详情，请参阅 REGEXP_EXTRACT 文档。

   • 过滤条件：如果您想将查询限制为包含特定属性或 span ID 的 span ，请添加过滤条件。该菜单列出了所有可用的过滤条件选项。您的选择会映射到 SQL 查询中的 WHERE 子句。

   • 排序依据：设置排序依据的列，以及排序是 升序还是降序。您的选择会映射到 SQL 查询中的 ORDER BY 子句。

   • 限制：设置结果表中的最大行数。您的选择会映射到 SQL 查询中的 LIMIT 子句。

5. 如需运行查询，请前往工具栏并选择运行查询 。

   Observability Analytics 会在表格中显示查询结果。不过，您可以创建 图表，也可以将表格或图表保存到 自定义信息中心。如需了解详情，请参阅 绘制 SQL 查询结果图表。

   如果工具栏显示在 BigQuery 中运行，则需要将 Observability Analytics 切换为使用默认查询引擎。如需进行此更改，请在 查询窗格的工具栏中，点击 设置 ，然后选择 Analytics（默认）。

示例：使用查询构建器分组和聚合数据

在查询构建器中选择列时，每个字段都包含一个菜单，您可以在其中添加分组和汇总。借助分组，您可以根据一列或多列的值将数据整理到各个组中；借助汇总，您可以对这些组执行计算以返回单个值。

您在列 元素中选择的每个字段都有一个附加菜单，其中包含以下选项：

• 无：不按此字段分组或聚合。
• 聚合：对列元素中列出的字段进行分组，除非 该字段具有聚合选择。对于这些字段，请通过对每个分组中的所有条目执行运算来计算值。 该运算可能是计算字段的平均值，也可能是计算每个分组中的条目数。
• 分组依据：按列元素中列出的所有字段对条目进行分组。

以下示例说明了如何构建一个查询，该查询先对条目进行分组，然后执行某种类型的聚合。

此示例介绍了如何使用查询构建器按开始时间、span 名称和 span 类型对 span 进行分组。然后，对于每个组，查询会计算平均时长（以纳秒为单位）。

如需构建此查询，请执行以下操作：

1. 在列 菜单中，选择 start_time、name、kind 和 duration_nano 字段。
2. 如需将开始时间截断为小时，请展开 start_time 列上的菜单，然后选择分组依据 。确保粒度菜单设置为小时 。

3. 点击应用 。

   当您为任何列选择分组依据 时，系统会按所有列对条目进行分组。在此示例中，条目按 start_time 的截断值、span 名称、span 类型和时长值进行分组。

   不过，此示例的目标是按截断的时间、span 名称和 span 类型对条目进行分组，然后针对每个组计算平均时长。在下一步中，您将修改分组并添加聚合。

4. 展开 duration_nano 字段上的菜单，选择 汇总，然后将 汇总 字段设置为 平均值。

   运行查询时，每一行对应一个组，该组由截断的时间、span 名称和 span 类型组成。每一行的最后一个条目是该组中所有条目的平均时长。

   此查询的结果类似于以下内容：

   +-----------------------------------+----------------+----------+-----------------------+
   | Row | hour_timestamp              | span_name      | kind     | average_duation_nano  |
   |     | TIMESTAMP                   | STRING         | INTEGER  | FLOAT                 |
   +-----+-----------------------------+-----------+---------------+-----------------------+
   | 1   | 2025-10-09 13:00:00.000 EDT | http.receive   | 3        | 122138.22813990474
   | 2   | 2025-10-09 13:00:00.000 EDT | query.request  | 1        | 6740819304.390297
   | 3   | 2025-10-09 13:00:00.000 EDT | client.handler | 2        | 6739339098.409376
   

5. 您的查询可以包含多个聚合。例如，如需添加一个用于统计每个组中条目数的列，请执行以下操作：

   1. 在列 元素中，点击添加列 。
   2. 选择全部 (*) 。
   3. 在对话框中，选择汇总 ，为 汇总 选择计数 ，然后选择应用 。

   进行此更改后，分组保持不变。条目按截断的开始时间、span 名称和 span 类型进行分组。不过，对于每个组，查询会计算平均时长和条目数。

上一个示例对应的 SQL 查询如下所示：

WITH
  scope_query AS (
  SELECT
    *
  FROM
    `PROJECT_ID.global._Trace._AllSpans` )
SELECT
  -- Report the truncated start time, span name, span kind, average duration and number
  -- of entries for each group.
  TIMESTAMP_TRUNC( start_time, HOUR ) AS hour_start_time,
  name AS span_name,
  kind,
  AVG( duration_nano ) AS average_duration_nano,
  COUNT( * ) AS count_all
FROM
  scope_query
GROUP BY
  TIMESTAMP_TRUNC( start_time, HOUR ),
  name,
  kind
LIMIT
  100

后续步骤

• 保存和共享 SQL 查询。
• 绘制 SQL 查询结果图表。
• 示例 SQL 查询。
• 在 BigQuery 中查询关联的数据集。