使用搜索查询生成器调查跟踪

TraceQL 受 PromQL 和 LogQL 的启发，是一种用于选择跟踪的查询语言。TraceQL 提供了一种精确构建查询的方法，因此您可以快速定位所需数据。由于查询限制了搜索范围，因此结果返回速度更快。

要了解如何通过 TraceQL 进行查询的更多信息，请参阅 TraceQL 文档。

位于 Grafana 的 Explore > Query type > Search 中的搜索查询生成器提供了下拉列表和文本字段，帮助您编写查询。

使用查询生成器启用搜索

此功能在 Grafana 10（及更高版本）和 Grafana Cloud 中自动可用。

要在自托管的 Grafana 10.1 及更低版本中启用 TraceQL 查询生成器，请启用 traceqlSearch 功能开关。

使用搜索编写 TraceQL 查询

位于 Grafana 的 Explore > Query type > Search 中的搜索查询生成器提供了下拉列表和文本字段，帮助您编写查询。您的选择会自动生成 TraceQL 查询。

该生成器允许您以最少的点击次数运行最常见的查询。您无需了解底层查询语言或数据库架构即可使用它。

生成器支持 TraceQL 功能的子集，包括一些结构运算符（>>, >, =~, !=）。

要访问搜索，请选择您的 Tempo 数据源，然后选择Explore，再选择Query type > Search。您可以使用查询生成器按资源服务名称、span 名称、持续时间、一个或多个标签搜索跟踪数据。此页面上的示例使用默认过滤器。

此外，您可以添加查询生成器块、查看查询历史记录，并使用Inspector查看详细信息。

Screenshot of the Tempo Search query type — Tempo 搜索查询类型截图

执行搜索

要执行搜索，您需要选择过滤器，然后运行查询。结果显示在查询生成器下方。截图标识了用于执行搜索的区域。

编号	名称	操作	评论
1	数据源	使用数据源下拉列表选择 Tempo 数据源。	每个数据源都有自己的搜索版本。此搜索特定于 Tempo 数据源。
2	查询类型	选择搜索。
3	选择过滤器	选择一个或多个过滤器。	可选。您可以在“搜索”选项卡中执行空查询。在 TraceQL 中，`{}` 是一个有效的查询，是提供所有跟踪或 span 列表的默认查询。
4	过滤器条件	为一个或多个过滤器选择选项。例如，您可以定义一个过滤器，其中Service Name (`resource.service.name`) 等于 (`=`) `user`。	可选。必须至少定义一个标签或过滤器。
5	标签和按...聚合	添加 span、资源或无范围的标签，并定义其条件。使用按...聚合对结果进行分组。	可选。
6	TraceQL 查询	显示由您的选择构建的 TraceQL 查询。	当您选择运行查询时，此 TraceQL 查询将被执行。

每个查询都搜索选定时间范围的数据。默认情况下，查询针对过去一小时的数据运行。选择运行查询左侧的时间范围，选择查询运行的数据时间范围。阅读仪表盘时间范围文档了解更多信息。

要访问搜索查询生成器，请遵循以下步骤：

登录 Grafana。
选择您的 Tempo 数据源。
从菜单中选择Explore，然后选择Query type > Search。

定义过滤器

使用过滤器，您可以通过选择Service Name、Span Name、Status或Duration来优化查询返回的数据。Duration表示 span 时间，通过从 span 的开始时间减去结束时间计算得出。

Grafana 管理员可以使用 Tempo 数据源配置更改默认过滤器。过滤器可以通过运算符进行限制。字段类型决定了可用的运算符。例如，Span Name和Service Name是字符串字段，因此比较运算符为等于 (=)、不等于 (!=)、匹配正则表达式 (=~) 或不匹配正则表达式 (!~)。Duration是持续时间字段类型，使用范围选择器 (>, >=, <, <=)。

当您为同一过滤器选择多个值时，Grafana 会自动将运算符更改为正则表达式 (regex) 运算符 =~，并将值与 | 连接。此功能仅适用于带有下拉值选择的字段。

例如，如果您选择 Span Name = get，然后选择 Span Name = log_results_cache，运算符下拉列表会从 = 更改为 =~，并且 get 和 log_results_cache 都列在 Span Name 字段中。生成的查询将更新为：

{duration>5ms && duration<10ms && name=~"get|log_results_cache"}

要定义过滤器，请按照以下步骤操作：

选择一个过滤器。
从下拉列表中选择一个比较运算符。
仅限Service Name、Span Name和Status：从下拉列表中选择一个或多个值。
仅限Duration：输入范围的值和单位，并为下拉列表选择比较运算符。单位可以是纳秒 (ns)、毫秒 (ms)、秒 (s)、分钟 (m) 和小时 (h)。

您可以选择运行查询执行查询，或者定义标签后再运行查询。

定义标签

您可以向查询添加任何标签，以进一步过滤结果。可以按范围（span 或 resource）或无范围选择标签。如果选择无范围，则会搜索所有标签以查找匹配项。

要添加标签，请按照以下步骤操作：

选择 span、resource 或 unscoped。
从选择标签下拉列表中选择一个标签。
选择一个比较运算符。
从选择值下拉列表中选择一个值。此字段根据标签填充。
可选：选择 + 添加另一个标签。

可选：使用按...聚合

警告
指标摘要 API 和按...聚合功能在 Grafana Cloud 和 Grafana 11.3 及更高版本中已被弃用。它将在未来的版本中移除。

使用按...聚合，您可以计算符合过滤条件的 kind=server 的 spans 的 RED 指标（总 span 计数、错误率 span 和延迟信息），并按一个或多个属性分组。此功能基于指标摘要 API。指标摘要仅计算最近一小时内接收到的 spans 的摘要。更多信息，请参阅跟踪到指标：Grafana Tempo 中使用按...聚合的即时 RED 指标。

按...聚合默认禁用。在 Grafana 中启用 metricsSummary 功能开关以使用此功能。

您的 Grafana Tempo 数据源还必须指向一个启用了Metrics Summary API的 Tempo 数据库。联系 Grafana Support 在 Grafana Cloud 中启用此功能。

使用按...聚合

当您使用按...聚合时，您的选择决定了信息在表格中如何报告。表格中列出了与您的数据中选择匹配的每个组合。每个聚合值（例如 intrinsic:name）在结果表格中都有相应的列。

例如，名称匹配 GET /:endpoint 且 span.http.user_agent 为 k6/0.46 的 span 出现在 31,466 个 span 中。查询结果不是按跟踪和相关 span 列出，而是按按...聚合中的选择分组。

RED 指标是针对您的数据中找到的每个名称和用户代理组合计算的。

截图显示了针对 mystical-server 服务的所有成功 HTTP status_code API 调用。结果按按...聚合中使用的相同顺序显示。例如，按...聚合列出 intrinsic.name，后跟 span.http.user_agent。结果表格的第一列显示名称，然后是span.http.user_agent。