PromQL数据查询-云监控(CMS)-阿里云帮助中心

在日常运维与故障排查中，经常需要在命令行直接查询 Prometheus 指标数据。通过 CLI aliyun cms2 对云监控 Prometheus 实例执行 PromQL 查询和元数据查询。支持即时查询、范围查询，以及 Labels/Series 等元数据查询。

说明

PromQL 相关命令位于 metric promql 命令组下（如 aliyun cms2 metric promql query）。
--prometheus-id 同时兼容 Prometheus 实例 ID 和 Prometheus 视图 ID，均通过 GetPrometheusInstance 解析查询端点。

前提条件

已完成 CLI 工具安装与配置。
已创建 Prometheus 实例且有数据上报。

共享参数与鉴权方式

以下参数对 metric promql 下所有子命令生效：

参数	类型	默认值	说明
`--prometheus-id`	string		Prometheus 实例 ID，指定查询的目标实例（必填）。
`--network`	string	`internet`	网络类型：`internet` 或 `vpc`。
`--aliyun-lang`	string		语言设置（`zh` \\| `en`）
`--resource-group-id`	string		资源组 ID。

PromQL 查询使用以下鉴权顺序：

优先使用实例的 authToken（Bearer Token 鉴权）。
无 Token 时回退为使用 AK/SK 构造的 Basic Auth（SLS MetricStore 兼容模式：user 为 AccessKeyId，password 为 AccessKeySecret 或 AccessKeySecret$SecurityToken）。

metric promql query — 即时查询

在指定评估时间点执行 PromQL 即时查询，--time 缺省时使用当前时间。

# 基本查询
aliyun cms2 metric promql query --prometheus-id pi-abc123 --query 'up'

# 指定时间戳查询（RFC3339 格式）
aliyun cms2 metric promql query --prometheus-id pi-abc123 \
  --query 'node_memory_MemAvailable_bytes' \
  --time 2026-07-15T05:05:23Z

# 指定时间戳查询（Unix 秒）
aliyun cms2 metric promql query --prometheus-id pi-abc123 \
  --query 'node_cpu_seconds_total' --time 1784091923

# 通过 VPC 网络查询
aliyun cms2 metric promql query --prometheus-id pi-abc123 \
  --network vpc --query 'up'

参数	类型	说明
`--query`	string	PromQL 表达式（必填）
`--time`	string	评估时间戳（RFC3339 或 Unix 秒，默认当前时间）

说明

时间值接受 RFC3339（如 2026-07-15T05:05:23Z）或 Unix 秒（如 1784091923）。
query 禁止使用 --start/--end/--step 参数，范围查询请使用 query-range。

metric promql query-range — 范围查询

在时间窗口内执行 PromQL 范围查询，--start、--end、--step 均为必填。

# 查询过去 24 小时的 CPU 使用率
aliyun cms2 metric promql query-range --prometheus-id pi-abc123 \
  --query 'rate(container_cpu_usage_seconds_total[5m])' \
  --start '2026-07-15T05:18:01Z' \
  --end '2026-07-16T05:18:01Z' \
  --step 60s

# 使用 Unix 时间戳
aliyun cms2 metric promql query-range --prometheus-id pi-abc123 \
  --query 'node_memory_MemAvailable_bytes' \
  --start 1784092681 --end 1784179081 --step 300s

参数	类型	说明
`--query`	string	PromQL 表达式（必填）
`--start`	string	开始时间戳（RFC3339 或 Unix 秒，必填）
`--end`	string	结束时间戳（RFC3339 或 Unix 秒，必填）
`--step`	string	查询分辨率步长（必填），如 `60s`、`5m`、`1h`

说明

query-range 禁止使用 --time 参数，否则报错。
--step 支持 Prometheus 时长格式（如 15s、1m）。

metric promql labels — 列出 Label 名称

查询 Prometheus 中所有 Label 名称，对应 Prometheus HTTP API 的 /api/v1/labels。

说明

labels 输出的是原始 Prometheus API JSON（{"status":"success","data":...}），不经过 CLI 的 success 信封包装，可直接通过管道传给 jq 处理。

# 列出所有 Label 名称
aliyun cms2 metric promql labels --prometheus-id pi-abc123

# 指定时间范围
aliyun cms2 metric promql labels --prometheus-id pi-abc123 \
  --start '2026-07-16T04:05:23Z' --end '2026-07-16T05:05:23Z'

# 按 Series Selector 过滤
aliyun cms2 metric promql labels --prometheus-id pi-abc123 --match 'up'

参数	类型	说明
`--start`	string	开始时间戳（可选）
`--end`	string	结束时间戳（可选）
`--match`	stringArray	Series Selector（可选，可重复使用）

metric promql label-values — 列出 Label 值

查询指定 Label 名称的所有值，对应 Prometheus HTTP API 的 /api/v1/label/<name>/values。

# 列出所有 metric 名称
aliyun cms2 metric promql label-values __name__ --prometheus-id pi-abc123

# 列出某 Label 的值，按 Selector 过滤
aliyun cms2 metric promql label-values job --prometheus-id pi-abc123 \
  --match 'up{namespace="monitoring"}'

# 通过管道传递给 jq
aliyun cms2 metric promql label-values __name__ --prometheus-id pi-abc123 | jq '.data[]'

参数	类型	说明
`<label_name>`	位置参数	Label 名称（必填，恰好一个）
`--start`	string	开始时间戳（可选）
`--end`	string	结束时间戳（可选）
`--match`	stringArray	Series Selector（可选，可重复使用）

metric promql series — 查找匹配的 Series

查找匹配指定 Selector 的 Series，对应 Prometheus HTTP API 的 /api/v1/series。

# 基本 Series 匹配
aliyun cms2 metric promql series --prometheus-id pi-abc123 \
  --match 'up' --start '2026-07-16T04:18:02Z' --end '2026-07-16T05:18:02Z'

# 多个 matcher
aliyun cms2 metric promql series --prometheus-id pi-abc123 \
  --match 'node_cpu_seconds_total{mode="idle"}' \
  --match 'node_memory_MemTotal_bytes' \
  --start 1784175482 --end 1784179082

参数	类型	说明
`--match`	stringArray	Series Selector（必填，可重复使用，至少一个）
`--start`	string	开始时间戳（必填）
`--end`	string	结束时间戳（必填）

子命令参数总结

子命令	特有参数	说明
`query`	`--query`、`--time`	即时查询，`--query` 必填
`query-range`	`--query`、`--start`、`--end`、`--step`	范围查询，四者均必填
`labels`	`--start`、`--end`、`--match`	均可选
`label-values`	`<label_name>`（位置参数）、`--start`、`--end`、`--match`	`<label_name>` 必填
`series`	`--match`、`--start`、`--end`	均为必填

SLS MetricStore 响应

阿里云 Prometheus 数据面使用 SLS MetricStore 实例，其 Prometheus HTTP API 在标准响应基础上扩展了 slsStatus 字段。

重要

HTTP 200 + slsStatus 表示数据可能不完整。CLI 层面的 success: true 仅代表 HTTP 调用成功，不保证数据完整性。

slsStatus.retryPolicy 含义如下（CLI 不自动重试，需外部实现）：

retryPolicy	含义	建议
`None`	相同请求必然相同错误	不重试，修改查询条件
`Once`	限流等临时原因	等待 300 ms 以上重试一次
`Continuous`	服务端问题，可能恢复	退避重试（300 ms → 翻倍 → 上限 10 s）

使用限制

仅 GET 请求，超长 PromQL 表达式可能遇到 URL 长度限制。
labels/label-values/series 会显式拒绝 --query/--time/--step 参数。
--match 使用 stringArray 类型，不会对逗号分隔值进行拆分，包含逗号的 PromQL Selector 可安全使用。
CLI 为单次执行工具，不实现 slsStatus.retryPolicy 自动重试。