菜单
文档breadcrumb arrow Grafana Tempobreadcrumb arrow TraceQLbreadcrumb arrow TraceQL 指标查询breadcrumb arrow TraceQL 指标函数
开源

TraceQL 指标函数

TraceQL 支持 rate, count_over_time, min_over_time, avg_over_time, quantile_over_time, histogram_over_time 和 compare 函数。

可用函数

这些函数可以作为运算符添加到任何 TraceQL 查询的末尾。

rate
计算每秒匹配的 Span 数量。
count_over_time
计算每个时间间隔内匹配的 Span 数量（请参阅 step API 参数）。
min_over_time
返回每个时间间隔内所有匹配 Span 的指定属性的最小值（请参阅 step API 参数）。
max_over_time
返回每个时间间隔内所有匹配 Span 的指定属性的最大值（请参阅 step API 参数）。
avg_over_time
返回每个时间间隔内所有匹配 Span 的指定属性的平均值（请参阅 step API 参数）。
quantile_over_time
指定间隔内值的分位数。
histogram_over_time
随时间评估频率分布。例如：histogram_over_time(duration) by (span.foo)。
compare
用于将 Span 流分割成两组：选择组和基线组。该函数返回 Span 上找到的所有属性的时间序列，以突出显示两组之间的差异。

rate 函数

rate 函数计算每秒匹配给定 Span 选择器的 Span 数量。

参数

无。

示例

以下查询显示按服务和 Span 名称划分的错误率。这是一种 TraceQL 特有的方法来收集速率指标，这些指标原本会由 Span 指标处理器生成。

例如，此查询

{ status = error } | rate() by (resource.service.name, name)

等同于使用 Span 生成的指标并运行该查询。

此示例计算来自服务 foo 的错误 Span 的速率。速率是 spans/sec（每秒 Span 数）的量。

{ resource.service.name = "foo" && status = error } | rate()

结合 by() 运算符，这会变得更加强大。

{ resource.service.name = "foo" && status = error } | rate() by (span.http.route)

此示例仍计算服务 foo 中的错误 Span 的速率，但指标按 HTTP 路由细分。例如，这可以帮助您确定 /api/sad 的错误 Span 速率高于 /api/happy。

count_over_time 函数

count_over_time() 函数计算每个时间间隔内匹配的 Span 数量。计数的间隔由 step 参数设置。

step 参数

step 参数定义了返回的时间序列的粒度。例如，step=15s 在时间范围内每 15 秒返回一个数据点。默认情况下，step 根据查询开始时间和结束时间自动选择一个动态值。

用于 step 的任何值都需要包含持续时间值，例如 30s 表示秒，或 1m 表示分钟。

您可以使用 Grafana Explore 或 Tempo API 配置此参数。有关使用 API 的信息，请参阅 step API 参数。

使用 Grafana Explore 检查或更改 step 值

  1. 选择您的 Tempo 数据源。
  2. 选择搜索或TraceQL查询类型选项卡。
  3. 展开指标选项以查看Step值。

The Step value in the Metrics options in Grafana Explore

示例

此示例计算名称为 "GET /:endpoint" 的 Span 的数量，并按状态码细分。您可能会看到有 10 个状态码为 200 的 "GET /:endpoint" Span 和 15 个状态码为 400 的 "GET /:endpoint" Span。

{ name = "GET /:endpoint" } | count_over_time() by (span.http.status_code)

min_over_time、max_over_time 和 avg_over_time 函数

min_over_time() 函数允许您通过计算数值属性的最小值来聚合它们。例如，您可以选择计算一组 Span 的最小持续时间，或者您可以选择计算您附加到 Span 的自定义属性（如 span.shopping.cart.entries）的最小值。计算最小值的间隔由 step 参数设置。

max_over_time() 函数允许您通过计算数值的最大值来聚合它们，例如非常重要的 Span 持续时间。计算最大值的间隔由 step 参数设置。

avg_over_time() 函数允许您通过计算数值的平均值来聚合它们，例如非常重要的 Span 持续时间。计算平均值的间隔由 step 参数设置。

更多信息请参阅 step API 参数。

参数

您想要计算最小值、最大值或平均值的数值字段。

示例

此示例计算所有名称为 "GET /:endpoint" 的 Span 中每个 http.target 的最小持续时间。Span 上的任何数值属性都可以计算。

{ name = "GET /:endpoint" } | min_over_time(duration) by (span.http.target)

此示例计算所有名称为 "GET /:endpoint" 的 Span 的最小状态码值。

{ name = "GET /:endpoint" } | min_over_time(span.http.status_code)

此示例计算所有名称为 "GET /:endpoint" 的 Span 中每个 http.target 的最大持续时间。

{ name = "GET /:endpoint" } | max_over_time(duration) by (span.http.target)
{ name = "GET /:endpoint" } | max_over_time(span.http.response.size)

此示例计算所有名称为 "GET /:endpoint" 的 Span 中每个 http.status_code 的平均持续时间。

{ name = "GET /:endpoint" } | avg_over_time(duration) by (span.http.status_code)
{ name = "GET /:endpoint" } | avg_over_time(span.http.response.size)

quantile_over_time 和 histogram_over_time 函数

quantile_over_time() 和 histogram_over_time() 函数允许您聚合数值，例如非常重要的 Span 持续时间。您可以在同一个查询中指定多个分位数。

以下示例计算名称为 GET /:endpoint 的所有 Span 的 duration 属性的第 99、90 和 50 个百分位数。

{ name = "GET /:endpoint" } | quantile_over_time(duration, .99, .9, .5)

您可以按任何 Span 或资源属性进行分组。

{ name = "GET /:endpoint" } | quantile_over_time(duration, .99) by (span.http.target)

分位数不限于 Span 持续时间。Span 上的任何数值属性都可以。为了展示这种灵活性，请看这个关于 span.http.status_code 的无意义分位数示例

{ name = "GET /:endpoint" } | quantile_over_time(span.http.status_code, .99, .9, .5)

这计算名称为 GET /:endpoint 的所有 Span 的 status_code 属性值的第 99、90 和 50 个百分位数。这不太可能提供任何有用的信息（状态码中位数 347 意味着什么？），但它确实有效。

再举一个例子，假设有一个自定义属性，如 span.temperature。您可以使用类似的查询来了解所有 Span 的温度的第 50 个和第 95 个百分位数是多少。

compare 函数

compare 函数用于将一组 Span 分割成两组：选择组和基线组。它返回 Span 上找到的所有属性的时间序列，以突出显示两组之间的差异。

这是一个强大的函数，最好通过使用 追踪钻取中的比较选项卡 来理解。您也可以通过查看下面的示例输出来理解此函数。

该函数与其他指标函数一样使用：当它位于任何追踪查询之后时，它会将查询转换为指标查询：...any spanset pipeline... | compare({subset filters}, <topN>, <start timestamp>, <end timestamp>)

示例

{ resource.service.name="a" && span.http.path="/myapi" } | compare({status=error})

此函数通常作为即时查询运行。即时查询在选定时间范围的末尾返回单个值。即时查询 执行更快，结果通常更容易理解。当作为范围查询运行时，返回值可能会超出 gRPC 有效负载。

参数

compare 函数有四个参数

  1. 必需。第一个参数是一个 spanset 过滤器，用于选择 Span 的子集。此过滤器针对传入的 Span 执行。如果匹配，则该 Span 被视为选择组的一部分。否则，它是基线组的一部分。常见的过滤器预计是类似 {status=error}（错误有什么不同？）或 {duration>1s}（慢 Span 有什么不同？）之类的表达式。

  2. 可选。第二个参数是每个属性返回的前 N 个值。如果属性在选择组或基线组中超出此限制，则仅返回前 N 个值（基于频率），并且输出中会包含该属性的错误指示器（见下文）。默认为 10。

  3. 可选。以 Unix 纳秒为单位的开始和结束时间戳，除了过滤器之外，还可用于按时间约束选择窗口。例如，整个查询可能涵盖过去一小时，而选择窗口仅涵盖发生异常的 5 分钟时间段。必须同时提供这两个时间戳，或都不提供。

输出

输出是 Span 中找到的每个属性/值的扁平时间序列。

每个时间序列都有一个标签 __meta_type，指示它属于哪个组，可以是 selection 或 baseline。

示例输出时间序列

{ __meta_type="baseline", resource.cluster="prod" } 123
{ __meta_type="baseline", resource.cluster="qa" } 124
{ __meta_type="selection", resource.cluster="prod" } 456   <--- significant difference detected
{ __meta_type="selection", resource.cluster="qa" } 125
{ __meta_type="selection", resource.cluster="dev"} 126  <--- cluster=dev was found in the highlighted spans but not in the baseline

当属性达到 topN 限制时，还会出现错误指示器。此示例表示属性 resource.cluster 的值过多。

{ __meta_error="__too_many_values__", resource.cluster=<nil> }