通过cURL调用Prometheus API获取指标值时遇语法解析错误

问题场景 #

想要在bash脚本里用cURL从Prometheus获取kafka_consumergroup_lag指标的1分钟内数值，之前用/api/v1/series端点能查到序列存在，但加时间范围[1m]时报错。

成功查询序列的命令及结果 #

执行以下命令可确认指标序列存在：

URL="https://192.168.0.11:9090"

curl -g "$URL/api/v1/series?" \
  --data-urlencode 'match[]=kafka_consumergroup_lag{consumergroup="obfuscated",topic="output_obfuscated",partition="2"}'

返回结果：

{
  "status": "success",
  "data": [
    {
      "__name__": "kafka_consumergroup_lag",
      "consumergroup": "obfuscated",
      "instance": "192.168.0.11:9308",
      "job": "kafka-exporter",
      "partition": "2",
      "topic": "output_obfuscated"
    }
  ]
}

错误的尝试及报错 #

尝试添加时间范围[1m]时执行以下命令：

curl -g "$URL/api/v1/series?" \
  --data-urlencode 'match[]=kafka_consumergroup_lag{consumergroup="obfuscated",topic="output_obfuscated",partition="2"}[1m]' 

得到错误：

{
  "status": "error",
  "errorType": "bad_data",
  "error": "invalid parameter \"match[]\": 1:109: parse error: unexpected \"[\""
}

解决方案 #

/api/v1/series端点仅用于查询时间序列的元数据或确认序列是否存在，不支持时间范围查询语法。要获取指标的实际数值，需使用以下两个API端点：

1. 获取当前时刻的指标值（即时查询） #

使用/api/v1/query端点，查询当前的指标数值：

curl -g "$URL/api/v1/query?" \
  --data-urlencode 'query=kafka_consumergroup_lag{consumergroup="obfuscated",topic="output_obfuscated",partition="2"}'

2. 获取时间范围内的指标值（范围查询） #

如果需要获取过去1分钟内的指标数据，使用/api/v1/query_range端点，指定start、end和step参数：

# 获取过去1分钟内的指标，步长10秒
curl -g "$URL/api/v1/query_range?" \
  --data-urlencode 'query=kafka_consumergroup_lag{consumergroup="obfuscated",topic="output_obfuscated",partition="2"}' \
  --data-urlencode "start=$(date -d "-1 minute" +%s)" \
  --data-urlencode "end=$(date +%s)" \
  --data-urlencode 'step=10s'

• start：查询时间范围的起始时间（Unix时间戳）
• end：查询时间范围的结束时间（Unix时间戳）
• step：采样间隔，可根据数据密度调整

补充说明 #

Grafana界面中能正常执行是因为它自动选择了正确的API端点（即时或范围查询），而非/api/v1/series。

内容的提问来源于stack exchange，提问作者Ilya Shmadchenko