SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场promql-cli

promql-cli

部署与运维

查看项目

更新于 10-16 10:14

技能介绍

用途

promql-cli（github.com/nalbury/promql-cli）是一个用 Go 编写的 CLI，用于查询、分析和可视化 Prometheus 指标，同时适用于 PromQL 兼容引擎，包括 Thanos、Cortex、VictoriaMetrics、Grafana Mimir、Grafana Tempo 等。该技能用于指导用户完成安装、配置、查询、可视化、调试和 PromQL 编写等任务。

参考文件与阅读时机

在执行任务前应先阅读相关参考文件：

  • references/installation.md：用户需要安装 promql-cli 或配置主机、认证、token、密码、多主机时阅读。
  • references/usage.md：用户想发现指标/导出器/标签、运行查询或选择输出格式时阅读。
  • references/graphing.md：用户想在终端将 Prometheus 数据可视化为 ASCII 图表时阅读。
  • references/debugging.md：用户正在排查性能、延迟、错误、饱和度、数据缺口或查询成本问题时阅读。
  • references/promql-reference.md：用户需要编写 PromQL、理解指标类型、函数或聚合时阅读。

大多数任务可先读 references/usage.md；需要 PromQL 帮助时读 references/promql-reference.md；调试时同时阅读 references/debugging.md 和 references/promql-reference.md。

配置检查

运行任何查询前，先确认已配置主机：

promql 'up'   # 主机可达则成功；未配置则报连接错误
# 或
promql --host xxx 'up'

以下错误应视为配置或认证问题，并参考 references/installation.md：

  • dial tcp ... connection refused：配置地址上没有运行主机。
  • dial tcp ... no such host：主机名无法解析，配置中的主机错误。
  • error querying prometheus: ...401...：Bearer token 缺失或无效。
  • error querying prometheus: ...403...：token 有效但权限不足。
  • please specify an authentication type：认证参数只设置了一部分，建议改用配置文件。

出现上述情况时，不要替用户创建配置文件——配置文件可能包含 token、密码等凭据，绝不应经过 LLM。应引导用户自行设置：

“请手动创建 ~/.promql-cli.yaml，填入你的 Prometheus 主机（以及需要的凭据）。具体格式见 references/installation.md。准备好后告诉我。”

只有用户确认配置就绪后，才继续执行查询。

常用命令参考

promql 'up'                                          # 即时查询
promql 'rate(http_requests_total[5m])' --start 1h    # 范围查询（ASCII 图表）
promql 'up' --output csv                             # CSV 输出
promql 'up' --output json                            # JSON 输出
promql metrics                                       # 列出所有指标名
promql labels <metric>                               # 列出某指标的标签
promql meta <metric>                                 # 显示指标类型与帮助信息
promql --config ~/.promql-cli-prod.yaml 'up'         # 指定特定主机

关键原则

  • 对 counter 使用 rate()，不要使用原始值——原始 counter 只会递增，绝对值没有意义；rate() 给出每秒变化率，才是真正关心的量。
  • 调试时隔离单个实例——跨副本聚合会掩盖单实例异常；单个过载的 pod 隐藏在健康副本之后，不会体现在平均值中。
  • 在最内层选择器用标签匹配器尽早过滤——Prometheus 先求值选择器再执行函数，过滤太晚意味着扫描所有时间序列；尽早过滤可减少扫描数据量和查询延迟。
  • 对直方图，在 histogram_quantile() 之前，by 子句中要保留 le——该函数需要所有 le 桶来插值百分位；过早丢弃 le 会产生 NaN 或错误结果。
  • 范围查询优先使用 --output graph——ASCII 迷你图能紧凑地传达趋势方向（上升、下降、尖峰），便于 LLM 解析；原始时间戳表格需要心算建模。不要把成千上万行原始 JSON/CSV 送进 LLM 上下文——改用 --output graph；或先运行 --output graph，仅在检查窄窗口时用 --output table。
  • 将凭据存放在 ~/.promql-cli.yaml 和 ~/.promql_token，权限 chmod 600——通过 CLI 参数传 token 会暴露在 shell 历史和进程列表中。

查询成本规则

在任何查询会话前后都应遵守：

  • 始终使用 promql CLI——不要从 Python 脚本或 shell curl 调用 Prometheus HTTP API。CLI 统一处理认证、格式化和输出；Python API 调用绕开这些，产生需要解析的原始 JSON，放大上下文并掩盖模型最易解读的图表输出。
  • 先检查基数——查询不熟悉的指标前，先统计其时间序列数（count(metric_name)）。高基数指标若无标签过滤会超时或淹没输出。相关模式见 references/debugging.md。
  • 提前确认时间窗口——运行范围查询前始终先询问。大区间成本高；宁可多次短区间查询，也不要一次长区间查询。
  • 区分过去与近期——对新调查，询问用户想要过去事件（具体时间戳）还是近期趋势。若是近期，给出具体选项：最近一小时、一天、一周、一个月。
  • 在 Prometheus 内聚合——绝不要把原始序列拉到 Python 或 shell 中聚合。把 sum by(...)、avg by(...) 或 topk() 推入 PromQL 表达式——Prometheus 在服务端折叠序列。
  • 超时 = 查询过宽——若查询超过 15 秒，缩小范围：加标签过滤、缩短 --start，或加聚合包装。会话中后续查询也应用同样收窄的范围。
  • 数据缺口 → 先查 up——当指标显示数据缺失时，在诊断应用前先运行 up{job="...", instance="..."}。值为 0 确认导出器已下线。见 references/debugging.md。

该技能并非详尽无遗。请参阅 promql-cli 官方文档与示例获取最新信息。Context7 可作为可发现性平台提供帮助。若在 promql-cli 本身遇到 bug 或异常行为，请在 https://github.com/nalbury/promql-cli/issues 提交 issue。