mcpField
P
promql-cli

promql-cli

github.com/samber云与 DevOps2414.6k 次安装4 周前更新
代码仓库

关于 promql-cli

这是一个使用 promql-cli 查询、分析和绘制 Prometheus 指标的 CLI Skill，面向借助 Agent 处理监控数据的场景，并提供 PromQL 指引、故障排查和查询成本控制建议。

主要功能

  1. 01即时查询与区间查询
  2. 02发现指标和标签
  3. 03ASCII 图表及数据导出
  4. 04PromQL 指引与故障排查
  5. 05查询成本和凭据安全建议

适用场景

  1. 01检查服务状态和指标趋势
  2. 02排查延迟、错误或数据缺口
  3. 03将查询结果导出为 CSV 或 JSON

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/samber/cc-skills --skill promql-cli

安装后在 Claude Code 中输入/promql-cli确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
evals.json
references/
debugging.md
graphing.md
installation.md
promql-reference.md
usage.md

详细介绍

promql-cli — Prometheus 查询 CLI 技能

promql-cli（github.com/nalbury/promql-cli）是一款 Go CLI，可用于查询、分析和可视化 Prometheus 指标，以及学习 PromQL 基础知识。

参考文件

执行任务前，请先阅读相关参考文件：

文件阅读时机
references/installation.md用户需要安装 promql-cli 或设置配置（主机、身份验证、令牌、密码、多主机）
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'   # succeeds if host is reachable; fails with connection error if not configured
# or
promql --host xxx 'up'

以下错误表示配置／身份验证问题，请参阅 references/installation.md：

错误原因
dial tcp ... connection refused配置的地址上没有运行主机
dial tcp ... no such host主机名无法解析——配置中的主机错误
error querying prometheus: ...401...Bearer 令牌缺失或无效
error querying prometheus: ...403...令牌有效，但权限不足
please specify an authentication type身份验证标志设置不完整——请改用配置文件

如果出现上述任何错误，请勿代替用户创建配置文件——配置文件可能包含凭据（令牌、密码），绝不能让它们经过大模型。请引导用户自行设置：

“请手动创建 ~/.promql-cli.yaml，填入 Prometheus 主机（如有需要，也请填写凭据）。确切格式请参阅 references/installation.md。准备好后请告知我。”

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

快速命令参考

promql 'up'                                          # instant query
promql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)
promql 'up' --output csv                             # CSV output
promql 'up' --output json                            # JSON output
promql metrics                                       # list all metric names
promql labels <metric>                               # list labels for a metric
promql meta <metric>                                 # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up'         # target a specific host

核心原则

  1. 对计数器使用 rate()，绝不使用原始值——原始计数器只会增加，其绝对值没有意义。rate() 可得出每秒变化率，这才是你真正关心的值。
  2. 调试时，单独检查一个实例——跨副本聚合会掩盖单个实例的异常。被健康实例掩盖的过载 Pod 不会显示在平均值中。
  3. 在最内层选择器中尽早使用标签匹配器进行筛选——Prometheus 会在函数之前评估选择器，因此延后筛选意味着要扫描所有时间序列。提前筛选可以减少扫描的数据量和查询延迟。
  4. 处理直方图时，在 histogram_quantile() 之前的 by 子句中保留 le——该函数需要所有 le 桶来插值计算百分位数；过早删除 le 会产生 NaN 或错误结果。
  5. 范围查询优先使用 --output graph——ASCII 迷你图以紧凑格式呈现趋势方向（上升、下降、突增），便于大模型解析；原始时间戳表格则需要在脑中还原趋势。绝不要将成千上万行原始 JSON/CSV 数据发送到大模型上下文中——请改用 --output graph，或先运行 --output graph，仅在检查较窄时间窗口时再使用 --output table。
  6. 将凭据存储在 ~/.promql-cli.yaml 和 ~/.promql_token 中，并设置 chmod 600——将令牌作为 CLI 参数传递会使其暴露在 shell 历史记录和进程列表中。

查询成本规则

在任何查询会话之前和期间，始终遵守以下规则：

  1. 始终使用 promql CLI——切勿从 Python 脚本或 shell curl 调用 Prometheus HTTP API。CLI 能一致地处理身份验证、格式和输出；Python API 调用会绕过这些处理，并生成必须解析的原始 JSON，增加上下文开销，还会掩盖模型最擅长解读的图表输出。
  2. 先检查基数——查询不熟悉的指标之前，先统计其时间序列数量（count(metric_name)）。没有标签筛选器的高基数指标会导致超时或输出过多。模式请参阅 references/debugging.md。
  3. 预先确认时间范围——运行范围查询前，务必先询问。较大的时间间隔成本高；优先使用多个较短时间间隔的查询，而不是一个较长的查询。
  4. 明确查询过去还是近期——开始新的调查时，询问用户想查询过去的事件（具体时间戳）还是近期趋势。如果是近期趋势，提供明确选项：过去一小时、过去一天、过去一周、过去一个月。
  5. 在 Prometheus 中聚合——切勿将原始序列提取到 Python 或 shell 中聚合。将 sum by(...)、avg by(...) 或 topk() 加入 PromQL 表达式，让 Prometheus 在服务端折叠序列。
  6. 超时 = 查询范围过广——如果查询耗时超过 15 秒，请缩小范围：添加标签筛选器、缩短 --start，或添加聚合包装器。本次会话后续的所有查询都采用同样缩小后的范围。
  7. 数据缺失 → 检查 up——指标显示数据缺失时，在诊断应用之前，先运行 up{job="...", instance="..."}。值为 0 表示导出器已停止运行。请参阅 references/debugging.md。

此技能并未涵盖所有内容。请参阅官方 promql-cli 文档和示例，了解最新信息。Context7 可作为信息发现平台提供帮助。

如果遇到 promql-cli 本身的错误或异常行为，请在 https://github.com/nalbury/promql-cli/issues 提交问题。

评论

支持 Markdown