Prometheus HTTP API POST请求报错：query参数解析失败求助

核心问题：请求体格式不匹配 #

Prometheus的/api/v1/query端点POST请求不支持JSON格式的请求体，它只接受application/x-www-form-urlencoded格式的键值对参数。这是绝大多数人遇到这个错误的原因——你大概率用了JSON来传递query参数，导致Prometheus无法识别。

解决步骤 #

1. 设置正确的Content-Type头
   发送POST请求时，必须指定Content-Type: application/x-www-form-urlencoded，否则Prometheus无法解析请求体中的参数。
   示例curl命令：

   curl -X POST http://your-prometheus-instance/api/v1/query \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "query=your_long_promql_expression_here"
   

2. 用键值对格式传参
   请求体直接写成query=你的PromQL语句，不要用JSON结构（比如{"query": "xxx"}）。后者是无效的，Prometheus不会解析JSON里的query字段。

3. 特殊字符URL编码（可选但推荐）
   如果你的PromQL里包含空格、方括号、&等特殊字符，需要对它们进行URL编码，避免解析错误：

   • 空格替换为+或%20
   • 方括号[替换为%5B，]替换为%5D
   • 等号=替换为%3D
     比如原查询sum(rate(http_requests_total[5m])) by (endpoint)编码后应为：

   sum(rate(http_requests_total%5B5m%5D))+by+(endpoint)
   

4. 多参数传递（如果需要）
   如果要同时传time、timeout等参数，用&分隔键值对即可：

   curl -X POST http://your-prometheus-instance/api/v1/query \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "query=sum(rate(http_requests_total[5m]))&time=1698765432&timeout=10s"
   

错误示例（别这么做） #

以下是典型的错误请求，会触发你遇到的invalid parameter 'query'错误：

curl -X POST http://your-prometheus-instance/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "sum(rate(http_requests_total[5m]))"}'

内容的提问来源于stack exchange，提问作者אברגיל יעקובו