Skills
skills/platform-eaglelab.tcl.com/prometheus-query

prometheus-query

SKILL.md

环境配置

后端地址: https://idsaas-o.api.leiniao.com/ops-infra-proxy

认证方式: X-User-Api-Key: TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥

所有请求均通过 ops-infra-proxy 代理转发，使用 X-User-Api-Key header 鉴权，支持国内/海外双区域。

API 参考

文件 内容
references/prometheus.md Prometheus 查询接口（瞬时、区间、标签、series、元数据）
references/grafana.md Grafana 接口（Dashboard 列表、面板详情、PromQL 提取）

核心机制：三级查询 + 自动沉淀

当用户提出监控查询需求时，必须按以下顺序处理：

  1. 先查本地指标库 — 在 metrics/ 目录下的分类文件中查找匹配的指标定义
  2. 命中则直接使用 — 取出指标库中的 PromQL 模板，替换变量后执行
  3. 未命中 → 查 Grafana 面板目录 — 调用 GET /grafana/{region}/api/search 拉取所有 Dashboard 摘要
  4. 大模型阅读目录并选择 — 根据用户意图，从面板目录中判断最匹配的 Dashboard + Panel
  5. 提取 PromQL — 调用 GET /grafana/{region}/api/dashboards/uid/{uid} 获取选定 Panel 的完整 PromQL，替换变量后执行
  6. 都未命中 → 模型构造 — 仅在前两级都找不到时，才允许模型自行构造 PromQL
  7. 查询成功 → 自动沉淀 — 无论来源是 Grafana 还是模型构造，验证成功的查询必须追加到对应的 metrics/ 文件中
  8. 主动补全指标库 — 即使本地指标库命中，若判断现有指标不足以支撑完整分析，必须主动去 Grafana 查找补充指标，提取后执行并沉淀

本地指标库是"缓存"，Grafana 是"指标注册中心"，模型构造是"兜底"。越用越准，查询越来越快。

指标库结构

指标库位于 metrics/ 目录，按监控对象分类。查询前先用下表定位文件，只读对应文件，不要扫描全部。

快速关键词 → 文件映射

用户提到的关键词 读哪个文件
pod, 容器, k8s, namespace, deployment metrics/k8s-pod.md
节点, node, k8s集群, vm集群, prometheus集群 metrics/cluster.md
服务器, 主机, cpu, 内存, 磁盘, 网络, 负载 metrics/server.md
jvm, http接口, 线程池, 连接池, 应用, 服务 metrics/application.md
redis, 缓存, 命中率 metrics/redis.md
kafka, 消费, lag, topic, 积压 metrics/kafka.md
rabbitmq, 队列, 消息队列 metrics/rabbitmq.md
mysql, rds, 数据库 metrics/mysql.md
elasticsearch, es metrics/elasticsearch.md
mongodb, mongo metrics/mongodb.md
clickhouse, ck metrics/clickhouse.md
flink, jobmanager, taskmanager metrics/flink.md
hbase metrics/hbase.md
nacos metrics/nacos.md
nginx metrics/nginx.md
zookeeper, zk metrics/zookeeper.md
rocketmq metrics/rocketmq.md
activemq metrics/activemq.md
emqx, mqtt metrics/emqx.md
kong, 网关 metrics/kong.md
oss, nas, cos, cfs, 对象存储, 文件存储 metrics/oss-nas.md
slb, alb, nlb, lb, 负载均衡 metrics/loadbalance.md
自定义, 业务指标, 证书, cert, ssl, tls metrics/custom.md

指标库文件格式

每个指标条目遵循统一格式：

## 指标名称（中文）

- 关键词: 用于匹配用户意图的关键词列表
- 类型: instant | range
- 推荐步长: （仅 range 类型）
- 说明: 指标含义简述

​```promql
PromQL 模板（使用 {{变量名}} 占位）
​```

变量说明：
- `{{变量名}}`: 含义及示例值

变量替换规则

指标库中的 PromQL 使用 {{变量名}} 作为占位符，执行前必须替换为实际值：

常见变量 含义 示例
{{instance}} 目标实例 IP 或 IP:端口 10.14.1.12
{{namespace}} K8s 命名空间 production
{{pod}} Pod 名称或正则 api-server-.*
{{application}} 应用名称 order-service
{{cluster}} 集群名称或正则 kube-ack-prod
{{interval}} 速率计算窗口 5m

查询方式

所有查询通过 curl 直接调用代理接口，详细接口说明见 references/prometheus.md 和 references/grafana.md。

--overseas 逻辑：用户明确提到"国内"时只查 domestic；明确提到"海外/overseas/国际"时只查 overseas；未指定时两边都查，合并结果展示（先国内后海外，标注来源区域）。

瞬时查询示例

curl -s -G "https://idsaas-o.api.leiniao.com/ops-infra-proxy/prometheus/domestic/select/0/prometheus/api/v1/query" \
  -H "X-User-Api-Key: TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥" \
  --data-urlencode "query=<PromQL>"

区间查询示例

curl -s -G "https://idsaas-o.api.leiniao.com/ops-infra-proxy/prometheus/domestic/select/0/prometheus/api/v1/query_range" \
  -H "X-User-Api-Key: TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥" \
  --data-urlencode "query=<PromQL>" \
  --data-urlencode "start=<unix_ts>" \
  --data-urlencode "end=<unix_ts>" \
  --data-urlencode "step=<step>"

Grafana Dashboard 列表示例

curl -s -G "https://idsaas-o.api.leiniao.com/ops-infra-proxy/grafana/domestic/api/search" \
  -H "X-User-Api-Key: TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥" \
  --data-urlencode "type=dash-db" \
  --data-urlencode "limit=100"

Grafana 面板详情示例

curl -s "https://idsaas-o.api.leiniao.com/ops-infra-proxy/grafana/domestic/api/dashboards/uid/<uid>" \
  -H "X-User-Api-Key: TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥"

指标沉淀规范

查询成功后，将新指标追加到对应 metrics/ 文件末尾，格式如下：

---

## 指标名称（中文）

- 关键词: 关键词1, 关键词2
- 类型: instant
- 说明: 指标含义
- 来源: grafana (YYYY-MM-DD)

​```promql
PromQL 模板（{{变量名}} 占位）
​```

变量说明：
- `{{变量名}}`: 含义

追加前检查文件中是否已有相同 PromQL（去重），相同则跳过。

查询规范与约束

必须遵守

  1. 本地指标库优先 — 先查 metrics/ 目录，命中直接用
  2. 未命中查 Grafana — 先拉 Dashboard 列表，阅读后选定目标，再拉面板详情提取 PromQL
  3. 变量必须替换 — 执行前所有 {{变量}} 必须替换为实际值
  4. 禁止宽泛查询 — 不允许 {__name__=~".*"} 等无限制查询
  5. 必须带标签过滤 — 每条查询至少包含一个精确标签匹配
  6. 成功必沉淀 — 非本地指标库命中的查询，执行成功后必须追加到指标库
  7. node主机指标 — 先不带端口查询，大部分场景下不会有端口，除非是 k8s
  8. Windows 环境 — curl 命令注意转义问题，PromQL 中的双引号需转义

时间约束

项目 默认值
瞬时查询 当前时刻（不传 time）
区间查询默认范围 过去 30 分钟
区间查询最大范围 24 小时
默认步长 1m

步长建议：30m 以内用 15s，1h 用 1m，6h 用 5m，24h 用 15m。

结果解读规范

查询返回后不要直接输出原始 JSON，应：

  1. 用自然语言描述当前值和含义
  2. 多实例结果按值排序，突出最高/最低
  3. 区间查询描述趋势，标注峰值时间点
  4. 数值带单位（%, MB, req/s 等）
  5. 结果为空时说明可能原因
  6. 双区域查询时，分"国内"/"海外"两组展示
  7. AWS 资源统一存储在海外
Installs
2
Source
platform-eaglel…us-query
First Seen
Apr 1, 2026