TraceQL 查询语言

欢迎回到第 8 章的学习。在上一节，我们学习了如何在 Grafana 中查询 Traces。现在我们要学习 TraceQL 查询语言，这是 Tempo 的查询语言，类似于 PromQL 和 LogQL。

本节将学习：TraceQL 语法、属性查询、时间范围查询、以及聚合查询。

TraceQL 语法

TraceQL 查询语法是什么？ TraceQL 查询语法：

{属性选择器} 操作符 值 [时间范围]

。

TraceQL 支持哪些操作符呢？

=
：等于，精确匹配。
!=
：不等于。
=~
：正则匹配。
!~
：正则不匹配。
>
、
<
、
>=
、
<=
：数值比较，比如
```
duration > 1s
```
。
&&
：逻辑与，同时满足。
||
：逻辑或，满足其一。

查询示例：

{service_name="api-gateway"}
：查询服务名称。

{service_name="api-gateway"} && duration > 1s
：组合条件。

{http.status_code="500"}
：查询错误。

TraceQL 查询流程： TraceQL 查询 → 属性选择器 → 操作符 → 值 → 时间范围 → 返回匹配 Trace。

TraceQL 非常灵活，支持复杂的查询条件。

属性查询

TraceQL 支持哪些常见属性呢？

第一个是服务属性。

service_name

：服务名称，

service.namespace

：服务命名空间。

第二个是 HTTP 属性。

http.method

：HTTP 方法，

http.status_code

：HTTP 状态码，

http.url

：HTTP URL。

第三个是数据库属性。

db.system

：数据库系统，

db.name

：数据库名称，

db.operation

：数据库操作。

第四个是自定义属性。

user.id

：用户 ID，

order.id

：订单 ID，

environment

：环境名称。

查询示例：

服务查询：

{service_name="api-gateway"}

，

{service_name=~"api.*"}

HTTP 查询：

{http.status_code="500"}

，

{http.method="POST"} && {http.status_code="200"}

数据库查询：

{db.system="mysql"} && {db.operation="SELECT"}

自定义属性查询：

{user.id="12345"}

，

{environment="production"}

属性查询非常灵活，可以根据不同属性查询 Trace。

时间范围查询

TraceQL 时间范围语法是什么？

[时间范围]

。

时间范围支持哪些单位呢？

s
：秒。
m
：分钟。
h
：小时。
d
：天。
w
：周。

时间范围查询示例：

{service_name="api-gateway"} [5m]
：最近 5 分钟的 Trace。
{http.status_code="500"} [1h]
：最近 1 小时的错误 Trace。

{service_name="api-gateway"} && duration > 1s [1d]
：最近 1 天的慢 Trace。

时间范围的作用： 限制查询范围，只查询指定时间范围内的 Trace，提高查询性能，减少查询的数据量。

时间范围查询可以提高查询性能，分析特定时间段的 Trace。

聚合查询

TraceQL 支持哪些聚合函数呢？

count()
：计数，统计 Trace 数量。
sum()
：求和。
avg()
：平均值，计算平均耗时。
min()
：最小值，找出最小耗时。
max()
：最大值，找出最大耗时。

聚合查询示例：

count({service_name="api-gateway"})
：统计 Trace 数量。
avg(duration) by (service_name)
：计算平均耗时，按服务分组。
max(duration) by (service_name)
：计算最大耗时，按服务分组。

分组聚合：

by (属性)

按属性分组，

without (属性)

排除属性后分组。

聚合查询可以统计分析 Trace，计算性能指标。

TraceQL 查询语言总结

本节小结

在本节中，我们学习了 TraceQL 查询语言：

第一个是 TraceQL 语法。

{属性选择器} 操作符 值 [时间范围]

。

第二个是属性查询。 服务属性、HTTP 属性、数据库属性、自定义属性。支持灵活的属性查询。

第三个是时间范围查询。

[时间范围]

，支持 s/m/h/d/w。可以限制查询的时间窗口。

第四个是聚合查询。

count()

、

avg()

、

max()

、

by

分组。可以统计分析 Trace。

TraceQL 总结： TraceQL 包括基本语法、属性查询、时间范围、聚合查询。这些功能组合在一起，构成了一个强大的查询语言。

这就是 TraceQL 查询语言。掌握了 TraceQL，就可以灵活地查询和分析 Trace 数据。

在下一节，我们将开始学习第 9 章 - 后端集成。学习 Java Spring Boot + OpenTelemetry 集成。