查询和分析轨迹

预览

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

本文档介绍如何使用 Log Analytics 查询和分析轨迹数据，Log Analytics 提供基于 SQL 的查询界面。借助 SQL，您可以执行汇总分析，这有助于您生成数据分析和发现趋势。如需查看查询结果，请使用表格或图表。 您还可以将这些表格和图表保存到自定义信息中心。

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

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

关联的 BigQuery 数据集简介

您无需使用关联的 BigQuery 数据集即可查询轨迹数据，或查询轨迹数据和日志数据。 对于这些场景，您可以使用 Log Analytics 页面。如需了解如何查询日志数据，请参阅使用 Log Analytics 查询和分析日志。

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

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

本文档未介绍如何创建关联的数据集，也未介绍如何配置 Log 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. 如需获得加载 Log Analytics 页面、在跟踪记录数据上撰写、运行和保存私密查询所需的权限，请让管理员为您授予以下 IAM 角色：

   • Observability View Accessor (roles/observability.viewAccessor) 在您要查询的可观测性视图上。此角色支持 IAM 条件，可让您将授予的权限限制为仅针对特定视图。如果您未为角色授予附加条件，则正文可以访问所有可观测性视图。
   • 针对项目的 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 时，Log Analytics 会自动推理列的字段。如需查看这些推理字段在您的数据中出现的频率，请点击 选项，然后选择查看信息和说明。

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

   如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则表示您的Google Cloud 项目不包含名为 _Trace 的可观测性存储桶。如需了解如何解决此故障，请参阅跟踪存储初始化失败。

查询轨迹数据

本部分介绍了可用于查询轨迹数据的方法：

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

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

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

   转到 Log Analytics

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

   注意： 如果 Log Analytics（日志分析）页面上的窗口显示“开始使用 Log Analytics”消息，请在该窗口中点击 Close（关闭）。

2. 在视图菜单中，前往 轨迹部分，然后选择 _Trace.Spans._AllSpans。

   如果您没有看到名为 _Trace.Spans._AllSpans 的视图，则表示您的Google Cloud 项目不包含名为 _Trace 的可观测性存储桶。如需了解如何解决此故障，请参阅跟踪存储初始化失败。

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

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

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

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

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

5. 可选：修改查询。

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

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

   如果工具栏显示在 BigQuery 上运行，则需要切换 Log Analytics 以使用默认查询引擎。如需进行此更改，请在查询窗格的工具栏中，依次点击 设置和 Analytics（默认）。

输入并运行自定义查询

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

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

   转到 Log Analytics

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

   注意： 如果 Log Analytics（日志分析）页面上的窗口显示“开始使用 Log Analytics”消息，请在该窗口中点击 Close（关闭）。

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

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

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

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

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

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

     • PROJECT_ID：项目的标识符。
     • LOCATION：可观测性存储桶的位置。

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

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

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

   如果工具栏显示在 BigQuery 上运行，则需要切换 Log Analytics 以使用默认查询引擎。如需进行此更改，请在查询窗格的工具栏中，依次点击 设置和 Analytics（默认）。

构建、修改和运行查询

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

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

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

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

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

   转到 Log Analytics

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

   注意： 如果 Log Analytics（日志分析）页面上的窗口显示“开始使用 Log Analytics”消息，请在该窗口中点击 Close（关闭）。

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

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

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

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

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

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

     • 使用菜单汇总或分组数据。

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

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

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

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

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

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

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

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

   如果工具栏显示在 BigQuery 上运行，则需要切换 Log Analytics 以使用默认查询引擎。如需进行此更改，请在查询窗格的工具栏中，依次点击 设置和 Analytics（默认）。

示例：使用查询构建器对数据进行分组和汇总

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

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

• 无：不按此字段进行分组或汇总。
• 汇总：对列元素中列出的字段进行分组，除非该字段已选择汇总。对于这些字段，通过对每个分组中的所有条目执行运算来计算值。该操作可能是计算某个字段的平均值，也可能是统计每个分组中的条目数。
• Group By：按 Columns 元素中列出的所有字段对条目进行分组。

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

此示例介绍了如何使用查询构建器按开始时间、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 中查询关联的数据集。