Back to Details

promql-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

promql-cli — Prometheus Query CLI Skill

promql-cli — Prometheus查询CLI工具

promql-cli
(github.com/nalbury/promql-cli) is a Go CLI for querying, analyzing, and visualizing Prometheus metrics, plus PromQL fundamentals.
promql-cli
（github.com/nalbury/promql-cli）是一款基于Go语言的CLI工具，用于查询、分析和可视化Prometheus指标，同时涵盖PromQL基础知识。

Reference Files

参考文档

Read the relevant reference file(s) before executing tasks:
FileWhen to read
references/installation.md
User needs to install promql-cli or set up configuration (hosts, auth, token, password, multi-host)
references/usage.md
User wants to discover metrics/exporters/labels, run queries, or choose output formats
references/graphing.md
User wants to visualize Prometheus data as an ASCII chart in the terminal
references/debugging.md
User is investigating a performance issue, latency, errors, or saturation
references/promql-reference.md
User needs help writing PromQL, understanding metric types, functions, or aggregations
For most tasks, read 
references/usage.md
. For PromQL help, read 
references/promql-reference.md
. When debugging, read both 
references/debugging.md
and 
references/promql-reference.md
.
执行任务前请阅读相关参考文档：
文件阅读场景
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
。

Setup Check

配置检查

Before running any query, verify that a host is configured:
bash
promql 'up'   # succeeds if host is reachable; fails with connection error if not configured
运行任何查询前，请确认已配置主机：
bash
promql 'up'   # 若主机可达则执行成功；若未配置则会出现连接错误

or

或

promql --host xxx 'up'

Recognize these errors as a configuration/auth problem and refer to `references/installation.md`:

| Error | Cause |
| --- | --- |
| `dial tcp ... connection refused` | No host running at the configured address |
| `dial tcp ... no such host` | Hostname not resolved — wrong host in config |
| `error querying prometheus: ...401...` | Bearer token missing or invalid |
| `error querying prometheus: ...403...` | Token valid but insufficient permissions |
| `please specify an authentication type` | Auth flags partially set — use config file instead |

If any of these appear, **do not create config files on behalf of the user** — config files may contain credentials (tokens, passwords) that must never pass through an LLM. Instead, guide the user to set it up themselves:

> "Please create `~/.promql-cli.yaml` manually with your Prometheus host (and credentials if needed). See `references/installation.md` for the exact format. Let me know once it's ready."

Only after the user confirms the config is in place should you proceed with queries.
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`。配置完成后请告知我。"

仅当用户确认配置完成后，才可继续执行查询。

Quick Command Reference

快速命令参考

bash
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
bash
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'         # 指定目标主机

Key Principles

核心原则

  1. Use 
    rate()
    on counters, never raw values     — raw counters only ever increase; the absolute value is meaningless. 
    rate()
    gives the per-second change rate, which is what you actually care about.
  2. When debugging, isolate a single instance — aggregating across replicas masks per-instance anomalies. A single overloaded pod hidden behind healthy peers won't show up in averages.
  3. Filter early with label matchers in the innermost selector — Prometheus evaluates selectors before functions, so filtering late means scanning all time series. Early filters reduce data scanned and query latency.
  4. For histograms, keep 
    le
    in the 
    by
    clause     before 
    histogram_quantile()
    — the function needs all 
    le
    buckets to interpolate percentiles; dropping 
    le
    early produces 
    NaN
    or wrong results.
  5. Prefer 
    --output graph
    for range queries     — ASCII sparklines convey trend direction (rising, falling, spiking) in a compact format that LLMs parse well; raw timestamp tables require mental modeling.
  6. Store credentials in 
    ~/.promql-cli.yaml
    and 
    ~/.promql_token
    , chmod 600     — passing tokens as CLI args exposes them in shell history and process listings.
This skill is not exhaustive. Please refer to the official promql-cli documentation and examples for up-to-date information. Context7 can help as a discoverability platform.
If you encounter a bug or unexpected behavior in promql-cli itself, open an issue at https://github.com/nalbury/promql-cli/issues.
  1. 对计数器使用
    rate()
    ，切勿使用原始值    ——原始计数器只会持续增长，其绝对值毫无意义。
    rate()
    会返回每秒变化率，这才是您真正需要关注的内容。
  2. 调试时，隔离单个实例——跨副本聚合会掩盖单个实例的异常情况。一个过载的Pod若被健康的同伴掩盖，在平均值中不会显现出来。
  3. 在最内层选择器中尽早使用标签匹配器过滤——Prometheus会先评估选择器再执行函数，因此延迟过滤意味着要扫描所有时间序列。尽早过滤可减少扫描的数据量和查询延迟。
  4. 处理直方图时，在
    histogram_quantile()
    前的
    by
    子句中保留
    le
    ——该函数需要所有
    le
    桶来插值计算百分位数；过早移除
    le
    会产生
    NaN
    或错误结果。
  5. 范围查询优先使用
    --output graph
    ——ASCII迷你图以紧凑格式传达趋势方向（上升、下降、突增），便于大语言模型解析；原始时间戳表格则需要人工构建模型理解。
  6. 将凭据存储在
    ~/.promql-cli.yaml
    和
    ~/.promql_token
    中，并设置权限为chmod 600    ——通过CLI参数传递令牌会将其暴露在shell历史记录和进程列表中。
本工具的功能介绍并不详尽。如需最新信息，请参考promql-cli官方文档及示例。Context7可作为发现平台提供帮助。
如果您在使用promql-cli时遇到bug或意外行为，请在https://github.com/nalbury/promql-cli/issues提交问题。