17.5.1 PromQL基础语法与数据模型

PromQL基础语法与数据模型#

PromQL 基于时间序列数据模型进行查询与计算，核心对象是指标（metric），每条时间序列由指标名与一组标签（label）唯一标识，标签用于维度划分与过滤。每个时间序列包含随时间变化的样本点（timestamp, value）。

原理草图：指标到查询结果的流转#

文章图片

数据模型要点#

  • 指标名：以字母或下划线开头，后续可含字母、数字、下划线、冒号。
  • 标签集合：键值对形式，标签名遵循命名规范，标签值为字符串。
  • 时间序列：同一指标名但标签集合不同即为不同序列。
  • 样本类型：数值为 float，时间戳为毫秒级。

基础语法构成#

PromQL 表达式由选择器、函数、聚合、运算与过滤组合而成，最常用的基础语法是向量选择器。

即时向量选择器#

选择当前时刻样本：

http_requests_total

标签过滤#

  • 等值匹配：=
  • 不等匹配：!=
  • 正则匹配：=~
  • 反向正则：!~

示例：

http_requests_total{job="nginx", instance=~"10\\.0\\.1\\..*"}

指标类型与使用原则#

  • Counter（计数器）：单调递增，适用于请求数、错误数；配合 rate()、increase()。
  • Gauge（仪表盘）：可增可减，适用于温度、队列长度、内存使用。
  • Histogram（直方图）：支持分桶统计与分位数计算，使用 _bucket、_sum、_count。
  • Summary（摘要）：客户端计算分位数，使用 _sum、_count 与 quantile。

标签基数与命名规范#

  • 标签维度越多，时间序列数量指数增长，应控制高基数字段。
  • 推荐命名：metric_name{label_name="value"}，使用清晰业务含义，避免动态值作为标签。

安装与验证（用于本节练习）#

以下用于搭建最小可验证环境，便于执行 PromQL 示例：

1）下载并启动 Prometheus

# 以 Linux x86_64 为例
cd /opt
wget https://github.com/prometheus/prometheus/releases/download/v2.49.1/prometheus-2.49.1.linux-amd64.tar.gz
tar -zxvf prometheus-2.49.1.linux-amd64.tar.gz
cd prometheus-2.49.1.linux-amd64

# 启动 Prometheus，监听 9090
./prometheus --config.file=./prometheus.yml

2）打开 Web UI

http://<prometheus_ip>:9090

3）验证内置指标可查

up

预期：返回 Prometheus 自身的 up 指标，值为 1。

基础查询示例（带解释）#

# 1. 查看某实例 CPU 使用（非 idle）
node_cpu_seconds_total{mode!="idle", instance="10.0.1.10:9100"}
# 解释：选择 node_cpu_seconds_total 指标，过滤标签 mode!=idle

# 2. 过滤 5xx 请求
http_requests_total{job="api", status=~"5.."}
# 解释：status 标签正则匹配 500-599

# 3. 近 5 分钟平均每秒请求数
rate(http_requests_total{job="api"}[5m])
# 解释：Counter 使用 rate 计算每秒增长率

查询结果类型#

  • 即时向量（Instant Vector）：一组当前时间点样本。
  • 区间向量（Range Vector）：时间范围内样本序列。
  • 标量（Scalar）：单一数值。
  • 字符串（String）：极少使用，通常由函数返回。

命令与工具（PromQL 检查）#

使用 promtool 对表达式做语法检查：

# 在 Prometheus 解压目录
./promtool query instant http://localhost:9090 'up'
# 预期：输出 up 的当前值

排错清单（常见报错与定位）#

  1. 返回空结果
    - 检查标签是否写错、大小写是否一致。
    - 查询 label_values 类函数不可用（PromQL 无此函数），可在 UI 的 Graph 上逐步删减标签。
  2. 报错：parse error
    - 检查是否缺失括号或方括号，例如 rate(metric[5m])。
  3. 查询慢
    - 缩小时间范围、减少高基数标签过滤。
    - 优先用确切匹配 = 替代正则 =~。

练习#

  1. 查询 job="prometheus" 的 up 指标并确认返回 1。
  2. 写出 node_memory_MemAvailable_bytes 的即时向量查询。
  3. 将 http_requests_total 过滤出 status 为 4xx 的序列。
  4. 用 rate() 计算过去 1 分钟的请求速率，比较与 5 分钟窗口的差异。

以上内容为 PromQL 的基础语法与数据模型要点，后续可在向量类型、选择器、聚合与运算中扩展。