需要查询 Prometheus/PromQL 兼容引擎…

在已配置 Prometheus 或 PromQL 兼容后端并安装 promql-cli/jq 的环境中，执行即时/范围查询、指标发现、图表化输出和可观测性排障。

适用场景

解决思路

1. 在执行任务前，先阅读相关参考文件：安装或配置问题读 `references/installation.md`。
2. 发现指标/导出器/标签、运行查询或选择输出格式时，读 `references/usage.md`。
3. 需要把 Prometheus 数据可视化为终端 ASCII 图表时，读 `references/graphing.md`。
4. 调查性能问题、延迟、错误、饱和度、数据缺口或查询成本问题时，读 `references/debugging.md`。
5. 需要帮助编写 PromQL、理解指标类型、函数或聚合时，读 `references/promql-reference.md`。
6. 大多数任务先读 `references/usage.md`；需要 PromQL 帮助时读 `references/promql-reference.md`；调试时同时读 `references/debugging.md` 和 `references/promql-reference.md`。
7. 运行任何查询前，用 `promql 'up'` 或 `promql --host xxx 'up'` 验证已配置且可访问的 host。
8. 若出现 `dial tcp ... connection refused`，判断为配置地址没有运行中的 host，并参考 `references/installation.md`。
9. 若出现 `dial tcp ... no such host`，判断为主机名无法解析或配置中的 host 错误，并参考 `references/installation.md`。
10. 若出现 `error querying prometheus: ...401...`，判断为 Bearer token 缺失或无效，并参考 `references/installation.md`。
11. 若出现 `error querying prometheus: ...403...`，判断为 token 有效但权限不足，并参考 `references/installation.md`。
12. 若出现 `please specify an authentication type`，判断为认证标志设置不完整，改用配置文件。
13. 出现上述错误时，不要代用户创建配置文件；配置文件可能含 token/password 等凭证，不能让 LLM 经手。
14. 引导用户自行手动创建 `~/.promql-cli.yaml`，按 `references/installation.md` 填写 Prometheus host 和所需凭证，等用户确认配置完成后再继续查询。
15. 执行 instant query：`promql 'up'`。
16. 执行 range query 并输出 ASCII 图：`promql 'rate(http_requests_total[5m])' --start 1h`。
17. 输出 CSV：`promql 'up' --output csv`。
18. 输出 JSON：`promql 'up' --output json`。
19. 列出所有指标名：`promql metrics`。
20. 列出某个指标的标签：`promql labels <metric>`。
21. 查看指标类型和 help：`promql meta <metric>`。
22. 指定特定 host：`promql --config ~/.promql-cli-prod.yaml 'up'`。
23. 对 counter 使用 `rate()`，不要用原始值；原始 counter 只增，绝对值无意义，`rate()` 给出每秒变化率。
24. 调试时隔离单个实例；跨副本聚合会掩盖单实例异常，单个过载 pod 可能被健康副本的平均值隐藏。
25. 在最内层 selector 中用 label matchers 尽早过滤；Prometheus 先求值 selector 再执行函数，晚过滤会扫描全部时间序列；尽早过滤可减少扫描数据和查询延迟。
26. 对 histogram，在 `histogram_quantile()` 前的 `by` 子句中保留 `le`；函数需要所有 `le` bucket 来插值百分位，过早丢弃 `le` 会产生 `NaN` 或错误结果。
27. range query 优先用 `--output graph`；ASCII sparklines 能紧凑传达趋势方向，便于 LLM 解析；不要把成千上万行原始 JSON/CSV 塞进 LLM 上下文；先跑 `--output graph`，只在检查窄窗口时用 `--output table`。
28. 把凭证存放在 `~/.promql-cli.yaml` 和 `~/.promql_token`，并设置 `chmod 600`；不要把 token 作为 CLI 参数传入，以免暴露在 shell history 和进程列表。
29. 始终使用 promql CLI；不要从 Python 脚本或 shell `curl` 调用 Prometheus HTTP API；CLI 统一处理认证、格式化和输出，Python API 调用绕过这些并产生需解析的原始 JSON，膨胀上下文且掩盖模型最易解释的 graph 输出。
30. 查询陌生指标前先检查 cardinality：用 `count(metric_name)` 统计其时间序列；无 label 过滤的高基数指标会超时或淹没输出；参考 `references/debugging.md`。
31. 运行 range query 前先确认时间窗口；大区间成本高；优先用多个短区间查询而不是一个长区间查询。
32. 区分过去与近期：新调查时询问用户想看过去事件（特定时间戳）还是近期趋势；若近期，给出具体选项：last hour、last day、last week、last month。
33. 在 Prometheus 内聚合；不要把原始 series 拉到 Python 或 shell 再聚合；把 `sum by(...)`、`avg by(...)` 或 `topk()` 放进 PromQL 表达式，让 Prometheus 服务端折叠 series。
34. 查询超过 15s 说明范围太宽；减少范围：加 label filters、缩短 `--start` 或添加聚合 wrapper；本会话后续查询沿用同样收窄的范围。
35. 指标出现数据缺口时，在诊断应用前先运行 `up{job="...", instance="..."}`；值为 `0` 可确认 exporter 曾下线；参考 `references/debugging.md`。
36. 该技能并非详尽无遗；参考官方 promql-cli 文档和示例获取最新信息；Context7 可作为发现平台。
37. 如果遇到 promql-cli 本身的 bug 或异常行为，在 https://github.com/nalbury/promql-cli/issues 提 issue。

适用边界 · 注意事项

• 未安装 `promql` 和 `jq`，或环境不允许安装/使用它们时，不适用。
• 没有可访问的 Prometheus 或 PromQL 兼容引擎（Thanos、Cortex、VictoriaMetrics、Grafana Mimir、Grafana Tempo 等），或无法提供 host/认证凭证时，不适用。
• 需要让 LLM 代用户创建含凭证的配置文件，或不能让用户自行在本地完成配置时，不适用（应避免凭证经手 LLM）。