菜单
文档面包屑箭头 Grafana 文档面包屑箭头 数据源面包屑箭头 Tempo面包屑箭头 查询跟踪数据面包屑箭头 编写 TraceQL 查询
Grafana Cloud 企业版 开源版

使用编辑器编写 TraceQL 查询

TraceQL 是受 PromQL 和 LogQL 启发的查询语言，专为选择跟踪而设计。TraceQL 提供了一种精确查询的方法，以便您可以聚焦所需数据。查询结果返回更快，因为查询限制了搜索范围。

要了解更多关于如何使用 TraceQL 进行查询的信息，请参阅 TraceQL 文档。

Grafana 探索 中的 TraceQL 查询编辑器允许您通过跟踪 ID 进行搜索，并使用自动完成编写 TraceQL 查询。

The TraceQL query editor

开始之前

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

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

流和 gRPC

如果您正在尝试从您的托管 Grafana 使用前置网关（例如 nginx）查询自托管的 Grafana Tempo 或 Grafana Enterprise Traces 数据库，该网关（例如，nginx）必须允许 gRPC 连接。如果不允许，流将无法工作，查询将无法返回结果。

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

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

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

要访问查询编辑器，请按照以下步骤操作

  1. 登录 Grafana 或 Grafana Cloud。

  2. 从主菜单中选择 Explore。

  3. 选择一个 Tempo 数据源。

  4. 选择 TraceQL 选项卡。

  5. 在文本行中输入 { 开始您的查询。有关 TraceQL 语法帮助，请参阅构建 TraceQL 查询文档。

    可选：选择 从搜索复制查询 以将构建查询转移到编辑器。

  6. 可选：使用 时间选择器 下拉列表更改查询的时间和范围（有关说明，请参阅仪表板时间范围文档）。

  7. 完成查询后，选择 运行查询。

Query editor showing span results

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

按 TraceID 查询

要按其跟踪 ID 查询特定跟踪

  1. 从菜单中选择 Explore，选择所需 Tempo 数据源，并导航到 TraceQL 选项卡。
  2. 在查询字段中输入跟踪 ID。例如：41928b92edf1cdbe0ba6594baee5ae9
  3. 单击 运行查询 或使用键盘快捷键 Shift + Enter。

Search for a trace ID using the TraceQL query editor

使用自动完成编写查询

您可以使用查询编辑器的自动完成建议编写查询。编辑器检测 spansets 以提供相关的自动完成选项。它使用正则表达式（regex）来检测其是否在 spanset 内，并提供 Tempo API 的属性名称、作用域、内省名称、逻辑运算符或属性值，具体取决于当前情况的需求。

Query editor showing the auto-complete feature

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

  1. 从菜单中选择 Explore，选择所需 Tempo 数据源，并导航到 TraceQL 选项卡。

  2. 输入您的查询。随着您输入查询，自动完成建议作为下拉菜单出现。您输入的每个字母都会细化自动完成选项以进行匹配。

  3. 使用鼠标或箭头键选择任何选项。当所需的选项突出显示时，按键盘上的 Tab 键将选择添加到您的查询中。

  4. 完成您的查询后，选择 运行查询。

查看查询结果

查询结果以表格形式显示，例如在查询编辑器下的表格 - 跟踪中。每个与查询条件匹配的span（以及它所属的跟踪）都会被查询返回。如果没有过滤条件，则所有span都匹配并返回，同时带上它们关联的跟踪。

查询是在定义的时间间隔内进行的，可以是相对的（例如，过去3小时）或绝对的（例如，从X日期时间到Y日期时间）。查询响应也受到跟踪数量（限制）和spanset中span数量的限制（Span限制）。

TraceQL in Grafana

  1. TraceQL查询编辑器
  2. 查询选项：限制、Span限制和表格格式（跟踪或Span）。
  3. 跟踪（通过跟踪ID）。名称和服务列显示跟踪根span名称和相关服务。
  4. 与跟踪关联的Span。

从返回结果中选择跟踪ID将打开跟踪图。从返回结果中选择span将打开跟踪图并揭示跟踪图中的相关span。

有关span详细信息的更多信息，请参阅探索中的跟踪。

Selecting a trace ID or a span to view span details

关注跟踪或Span

在选项下，您可以选择将表格显示为关注跟踪或关注Span。

当将表格类型选项设置为Span时，跟踪和spanset将被扁平化为span的列表。将跟踪服务和跟踪名称添加到每个span的行中以添加上下文。

使用Span选项可以更容易地访问span以应用转换并在仪表板上绘制它们。

流式传输结果

Tempo数据源支持TraceQL查询的流式响应，因此您可以在整个查询完成之前看到部分查询结果。

注意

要在Grafana OSS v10.1及更高版本中使用此功能，请启用traceQLStreaming功能开关。此功能在Grafana Cloud中默认启用。

流式传输对搜索和TraceQL查询类型都可用，您将在结果表中立即看到传入跟踪的可见性。