使用编辑器编写 TraceQL 查询

TraceQL 受 PromQL 和 LogQL 启发，是一种用于选择追踪的查询语言。TraceQL 提供了一种 формулировка 精确查询的方法，以便您可以快速找到所需数据。查询结果返回更快，因为查询限制了搜索范围。

要了解如何通过 TraceQL 查询，请参阅TraceQL 文档。

Grafana Explore 中的 TraceQL 查询编辑器允许您按追踪 ID 搜索并使用自动完成功能编写 TraceQL 查询。

开始之前

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

要在自托管的 Grafana 9.3.2 及更早版本中使用 TraceQL 查询编辑器，您需要启用 traceqlEditor 功能开关。

流式传输和 gRPC

如果您尝试通过网关（例如 nginx）从托管的 Grafana 查询自管理的 Grafana Tempo 或 Grafana Enterprise Traces 数据库，则该网关（例如 nginx）必须允许 gRPC 连接。如果不允许，流式传输将不起作用，并且查询将无法返回结果。

如果您无法配置网关以允许 gRPC，请在托管的 Grafana 中停用流式传输。在 Grafana 11.2 及更高版本中，您可以从 Grafana 主菜单的连接 > 数据源中停用 Tempo 数据源设置中的流式传输选项。您也可以提交支持升级请求，以禁用托管的 Grafana 中的流式查询结果。

使用查询编辑器编写 TraceQL 查询

Tempo 数据源的 TraceQL 查询编辑器可帮助您在 Explore 中查询和显示 Tempo 的追踪。

访问查询编辑器的步骤如下：

登录 Grafana 或 Grafana Cloud。
从主菜单中选择探索。
选择 Tempo 数据源。
选择 TraceQL 选项卡。
在文本行输入 { 开始查询。有关 TraceQL 语法的帮助，请参阅构建 TraceQL 查询文档。
可选：选择从搜索复制查询将构建器查询传输到编辑器。
可选：使用时间选择器下拉列表更改查询的时间和范围（参阅文档获取说明）。
完成查询后，选择运行查询。

此视频提供了使用自定义标签分组创建 TraceQL 查询的示例。

按 TraceID 查询

要按追踪 ID 查询特定追踪：

从菜单中选择探索，选择所需的 Tempo 数据源，然后导航到 TraceQL 选项卡。
在查询字段中输入追踪 ID。例如：41928b92edf1cdbe0ba6594baee5ae9
点击运行查询或使用键盘快捷键 Shift + Enter。

使用自动完成编写查询

您可以使用查询编辑器的自动完成建议编写查询。编辑器会检测 spanset 并提供相关的自动完成选项。它使用正则表达式 (regex) 检测其是否在 spanset 内部，并根据当前情况提供属性名称、范围、固有名称、逻辑运算符或来自 Tempo API 的属性值。

锚定正则表达式

正则表达式在两端都被锚定。这种锚定使查询更快，并与 PromQL 的行为一致，其中正则表达式也是完全锚定的。

未锚定的查询，例如：{ span.foo =~ "bar" } 现在被视为：{ span.foo =~ "^bar$" }。

如果您在 Grafana 仪表盘中使用带有正则表达式的 TraceQL，并且想要未锚定的行为，请更新查询以使用未锚定的版本，例如 { span.foo =~ ".*bar.*"}。

使用自动完成创建查询

要使用自动完成功能创建查询，请按照以下步骤操作：

从菜单中选择探索，选择所需的 Tempo 数据源，然后导航到 TraceQL 选项卡。
输入您的查询。当您输入查询时，自动完成建议将显示为下拉列表。您输入的每个字母都会优化自动完成选项以进行匹配。
使用鼠标或方向键选择您想要的任何选项。当突出显示所需选项时，按键盘上的 Tab 将选择添加到查询中。
完成查询后，选择运行查询。

查看查询结果

查询结果显示在查询编辑器下方的表格中，例如表格 - 追踪。与查询条件匹配的每个 span（及其所属的追踪）都会由查询返回。如果没有过滤条件，则所有 span 都匹配，因此返回它们及其相关的追踪。

查询是针对定义的时间间隔执行的，可以是相对的（例如，最近 3 小时）或绝对的（例如，从 X 日期时间到 Y 日期时间）。查询响应也受追踪数量（限制）和每个 spanset 中的 span 数量（Span 限制）限制。

TraceQL 查询编辑器
查询选项：限制、Span 限制和表格格式（追踪或 Span）。
追踪（按追踪 ID）。名称和服务列显示追踪根 span 名称和相关的服务。
与追踪关联的 Span。

从返回结果中选择追踪 ID 会打开一个追踪图。选择返回结果中的 span 会打开一个追踪图并显示追踪图中的相关 span。

有关 span 详情的更多信息，请参阅Explore 中的追踪。

查询包含大量 span 的 spanset 可能会对性能产生负面影响。您可以使用 TraceQL 查询编辑器选项部分中的Span 限制字段。此字段设置每个 span set 返回的最大 span 数量。默认情况下，您可以为Span 限制值（或 spss 查询）设置的最大值为 100。在 Tempo 配置中，此值由 max_spans_per_span_set 参数控制，并可由您的 Tempo 管理员修改。Grafana Cloud 用户可以联系 Grafana 支持人员请求更改。输入高于默认值的值会导致错误。