菜单
文档breadcrumb arrow Grafana Lokibreadcrumb arrow 查询breadcrumb arrow 指标查询
开源

指标查询

指标查询通过对日志查询结果应用函数来扩展日志查询。这个强大的功能可以从日志中创建指标。

指标查询可用于计算错误消息的速率，或过去 3 小时内日志量最大的前 N 个日志源。

与解析器结合使用，指标查询还可以用于从日志行中的样本值（例如延迟或请求大小）计算指标。所有标签，包括提取的标签，都可用于聚合和生成新的序列。

范围向量聚合

LogQL 共享 Prometheus 的 范围向量 概念。在 Grafana Loki 中，选定的样本范围是选定的日志或标签值范围。

聚合应用于一段时间。Loki 使用与 Prometheus 相同的语法定义 时间持续时间。

Loki 支持两种类型的范围向量聚合：日志范围聚合和解包范围聚合。

日志范围聚合

日志范围聚合是查询后跟持续时间。函数应用于聚合持续时间内的查询。持续时间可以放在日志流选择器之后或日志管道的末尾。

函数

  • rate(log-range)：计算每秒的条目数
  • count_over_time(log-range)：计算给定范围内每个日志流的条目数。
  • bytes_rate(log-range)：计算每个流每秒的字节数。
  • bytes_over_time(log-range)：计算给定范围内每个日志流使用的字节数。
  • absent_over_time(log-range)：如果传递给它的范围向量有任何元素，则返回一个空向量；如果传递给它的范围向量没有元素，则返回一个值为 1 的单元素向量。（absent_over_time 对于在一段时间内标签组合不存在任何时间序列和日志流时发出警报很有用。）

示例

  • 计算 MySQL 作业在过去五分钟内的所有日志行。

    logql 
    count_over_time({job="mysql"}[5m])

  • 此聚合包括过滤器和解析器。它返回 MySQL 作业在过去几分钟内每个主机的每秒非超时错误率，并且仅包括持续时间超过十秒的错误。

    logql 
    sum by (host) (rate({job="mysql"} |= "error" != "timeout" | json | duration > 10s [1m]))

Offset 修饰符

offset 修饰符允许更改查询中各个范围向量的时间偏移。

例如，以下表达式计算 MySQL 作业在过去十分钟到五分钟内的所有日志，而不是过去五分钟内的日志。请注意，offset 修饰符始终需要紧跟在范围向量选择器之后。

logql 
count_over_time({job="mysql"}[5m] offset 5m) // GOOD
count_over_time({job="mysql"}[5m]) offset 5m // INVALID

解包范围聚合

解包范围使用提取的标签作为样本值，而不是日志行。但是，要选择聚合中将使用哪个标签，日志查询必须以解包表达式结尾，并可选择标签过滤器表达式来丢弃 错误。

解包表达式表示为 | unwrap label_identifier，其中 label_identifier 是用于提取样本值的标签名称。

由于标签值是字符串，默认情况下将尝试转换为浮点数（64 位），如果转换失败，则会将 __error__ 标签添加到样本中。或者，标签标识符可以由转换函数 | unwrap <function>(label_identifier) 包裹，这将尝试从特定格式转换标签值。

我们目前支持以下函数

  • duration_seconds(label_identifier)（或其简短等效形式 duration），它将从 go duration 格式（例如 5m、24s30ms）将标签值转换为秒。
  • bytes(label_identifier)，它将应用字节单位（例如 5 MiB、3k、1G）将标签值转换为原始字节。

用于对解包范围进行操作的受支持函数为

  • rate(unwrapped-range)：计算指定间隔内所有值之和的每秒速率。
  • rate_counter(unwrapped-range)：计算指定间隔内值的每秒速率，并将它们视为“计数器指标”
  • sum_over_time(unwrapped-range)：指定间隔内所有值的总和。
  • avg_over_time(unwrapped-range)：指定间隔内所有点的平均值。
  • max_over_time(unwrapped-range)：指定间隔内所有点的最大值。
  • min_over_time(unwrapped-range)：指定间隔内所有点的最小值
  • first_over_time(unwrapped-range)：指定间隔内所有点的第一个值
  • last_over_time(unwrapped-range)：指定间隔内所有点的最后一个值
  • stdvar_over_time(unwrapped-range)：指定间隔内值的总体标准方差。
  • stddev_over_time(unwrapped-range)：指定间隔内值的总体标准偏差。
  • quantile_over_time(scalar,unwrapped-range)：指定间隔内值的 φ-分位数 (0 ≤ φ ≤ 1)。
  • absent_over_time(unwrapped-range)：如果传递给它的范围向量有任何元素，则返回一个空向量；如果传递给它的范围向量没有元素，则返回一个值为 1 的单元素向量。（absent_over_time 对于在一段时间内标签组合不存在任何时间序列和日志流时发出警报很有用。）

除了 sum_over_time、absent_over_time、rate 和 rate_counter 之外，解包范围聚合还支持分组。

logql 
<aggr-op>([parameter,] <unwrapped-range>) [without|by (<label list>)]

可以通过包含 without 或 by 子句来用于聚合不同的标签维度。

without 从结果向量中删除列出的标签，同时保留所有其他标签。by 则相反，删除未在 by 子句中列出的标签，即使它们的标签值在向量的所有元素之间都相同。

有关使用解包表达式的查询示例，请参阅 解包示例。

内置聚合运算符

与 PromQL 类似，LogQL 支持内置聚合运算符的子集，这些运算符可用于聚合单个向量的元素，从而生成元素较少但具有聚合值的新向量

  • sum：计算标签的总和
  • avg：计算标签的平均值
  • min：选择标签的最小值
  • max：选择标签的最大值
  • stddev：计算标签的总体标准偏差
  • stdvar：计算标签的总体标准方差
  • count：计算向量中元素的数量
  • topk：按样本值选择最大的 k 个元素
  • bottomk：按样本值选择最小的 k 个元素
  • sort：返回按样本值排序的向量元素，升序排列。
  • sort_desc：与 sort 相同，但以降序排序。

聚合运算符可以用于聚合所有标签值或一组不同的标签值，方法是包含 without 或 by 子句

logql 
<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]

使用 topk 和 bottomk 时，parameter 是必需的。topk 和 bottomk 与其他聚合器不同，因为输入样本的子集（包括原始标签）将返回到结果向量中。

by 和 without 仅用于对输入向量进行分组。without 子句从结果向量中删除列出的标签，并保留所有其他标签。by 子句则相反，删除子句中未列出的标签，即使它们的标签值在向量的所有元素之间都相同。

有关使用向量聚合表达式的查询示例，请参阅 向量聚合示例。

函数

LogQL 支持一组内置函数。

  • vector(s scalar)：将标量 s 作为没有标签的向量返回。这与 Prometheus vector() 函数 的行为相同。vector 主要用于为原本不会返回任何值的序列返回值；当使用 LogQL 定义警报时，这可能很有用。

示例

  • 计算 traefik 命名空间在过去五分钟内的所有日志行。

    logql 
    sum(count_over_time({namespace="traefik"}[5m])) # will return nothing
  or
vector(0) # will return 0

概率聚合

topk 关键字允许您按样本大小查找数据流中最大的 1,000 个元素。当 topk 达到最大序列限制时，LogQL 还支持使用概率近似值；当 topk 达到最大序列限制时，approx_topk 是一个直接替换。

logql 
approx_topk(k, <vector expression>)

它仅支持即时查询，不支持分组。当内部向量的基数太高时，它很有用，例如，当它使用按结构化元数据标签进行的聚合时。