VictoriaMetrics Metrics Query

VictoriaMetrics 指标查询

Query VictoriaMetrics HTTP API directly via curl. Covers instant/range queries, label/series discovery, alerts, rules, instance diagnostics, raw data export, metric usage statistics, and config debugging tools.

通过curl直接查询VictoriaMetrics HTTP API。涵盖即时/范围查询、标签/序列发现、告警、规则、实例诊断、原始数据导出、指标使用统计以及配置调试工具。

Environment

环境配置

bash

undefined

bash

undefined

$VM_METRICS_URL - base URL

$VM_METRICS_URL - 基础URL

cluster: export VM_METRICS_URL="https://vmselect.example.com/select/0/prometheus"

集群模式: export VM_METRICS_URL="https://vmselect.example.com/select/0/prometheus"

single: export VM_METRICS_URL="http://localhost:8428"

单实例模式: export VM_METRICS_URL="http://localhost:8428"

$VM_AUTH_HEADER - auth header (set for prod, empty for local)

$VM_AUTH_HEADER - 认证头（生产环境设置，本地环境留空）

undefined

undefined

Auth Pattern

认证模式

All curl commands use conditional auth — works for both prod and local:

bash

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_METRICS_URL/api/v1/query?query=up" | jq .

When

VM_AUTH_HEADER

is empty,

-H

flag is omitted automatically.

所有curl命令使用条件认证——同时适用于生产和本地环境：

bash

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_METRICS_URL/api/v1/query?query=up" | jq .

当

VM_AUTH_HEADER

为空时，

-H

参数会自动省略。

Core Endpoints

核心端点

Instant Query

即时查询

bash

undefined

bash

undefined

Query at current time

查询当前时间的数据

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/query?query=up" | jq .

Query at specific time

查询指定时间的数据

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/query?query=up&time=2026-03-07T09:00:00Z" | jq .


Parameters: `query` (required), `time` (optional, RFC3339 or Unix seconds), `step`, `timeout`

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/query?query=up&time=2026-03-07T09:00:00Z" | jq .


参数：`query`（必填）、`time`（可选，RFC3339格式或Unix时间戳）、`step`、`timeout`

Range Query

范围查询

bash

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
  "$VM_METRICS_URL/api/v1/query_range?query=rate(http_requests_total[5m])&start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&step=5m" | jq .

Parameters:

query

(required),

start

(required),

end

(optional),

step

(required). Times in RFC3339 or Unix seconds.

bash

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
  "$VM_METRICS_URL/api/v1/query_range?query=rate(http_requests_total[5m])&start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&step=5m" | jq .

参数：

query

（必填）、

start

（必填）、

end

（可选）、

step

（必填）。时间格式支持RFC3339或Unix时间戳。

Labels Discovery

标签发现

bash

undefined

bash

undefined

All label names

获取所有标签名称

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/labels" | jq '.data[]'

Label values (label_name is a PATH parameter)

获取标签值（label_name为路径参数）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

Label values filtered by series matcher

通过序列匹配器过滤标签值

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={job="kubelet"}'
"$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

undefined

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={job="kubelet"}'
"$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

undefined

Series Discovery

序列发现

bash

undefined

bash

undefined

Find series matching selector

查找匹配选择器的序列

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={namespace="myapp"}'
"$VM_METRICS_URL/api/v1/series?limit=20" | jq '.data[].name'


Parameters: `match[]` (required), `start`, `end`, `limit`

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={namespace="myapp"}'
"$VM_METRICS_URL/api/v1/series?limit=20" | jq '.data[].name'


参数：`match[]`（必填）、`start`、`end`、`limit`

Metric Metadata

指标元数据

bash

undefined

bash

undefined

Search by metric name keyword

通过指标名称关键词搜索

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/metadata?metric=http_request&limit=10" | jq .


Parameters: `metric` (search keyword), `limit`.

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/metadata?metric=http_request&limit=10" | jq .


参数：`metric`（搜索关键词）、`limit`。

Alerts and Rules

告警与规则

bash

undefined

bash

undefined

All firing/pending alerts

获取所有触发/待处理的告警

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/alerts" | jq '.data.alerts[]'

All alerting and recording rules

获取所有告警规则和记录规则

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/rules" | jq '.data.groups[]'

undefined

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/rules" | jq '.data.groups[]'

undefined

Instance Diagnostics

实例诊断

bash

undefined

bash

undefined

TSDB cardinality stats

TSDB基数统计

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/tsdb" | jq .

Currently executing queries

当前正在执行的查询

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/active_queries" | jq .

Most frequent/slowest queries

最频繁/最慢的查询

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/top_queries?topN=10" | jq .

Version info

版本信息

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/buildinfo" | jq .

undefined

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/buildinfo" | jq .

undefined

Export Raw Data

导出原始数据

bash

undefined

bash

undefined

Export raw samples as JSON lines (one JSON object per line)

以JSON行格式导出原始样本（每行一个JSON对象）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]=http_requests_total'
-d 'start=2026-03-07T00:00:00Z' -d 'end=2026-03-07T12:00:00Z'
"$VM_METRICS_URL/api/v1/export" | head -5

Export with reduced memory usage (for large exports)

以低内存占用模式导出（适用于大规模导出）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={namespace="myapp"}'
-d 'start=2026-03-07T00:00:00Z' -d 'end=2026-03-07T01:00:00Z'
-d 'reduce_mem_usage=1'
"$VM_METRICS_URL/api/v1/export" > export.jsonl


Parameters: `match[]` (required), `start`, `end`, `reduce_mem_usage`. Output is JSON lines (not wrapped in a standard API response).

Each line: `{"metric":{"__name__":"...","label":"value"},"values":[...],"timestamps":[...]}`

Also available: `/api/v1/export/csv` (CSV format), `/api/v1/export/native` (binary, for import via `/api/v1/import/native`).

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={namespace="myapp"}'
-d 'start=2026-03-07T00:00:00Z' -d 'end=2026-03-07T01:00:00Z'
-d 'reduce_mem_usage=1'
"$VM_METRICS_URL/api/v1/export" > export.jsonl


参数：`match[]`（必填）、`start`、`end`、`reduce_mem_usage`。输出格式为JSON行（不包含标准API响应的包裹结构）。

每行格式：`{"metric":{"__name__":"...","label":"value"},"values":[...],"timestamps":[...]}`

还支持以下格式：`/api/v1/export/csv`（CSV格式）、`/api/v1/export/native`（二进制格式，可通过`/api/v1/import/native`导入）。

Series Count

序列数量统计

bash

undefined

bash

undefined

Total number of active time series

获取活跃时间序列的总数

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/series/count" | jq .


Note: can be slow on large databases and may return slightly inflated values.

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/series/count" | jq .


注意：在大型数据库上执行可能较慢，返回值可能略有偏高。

Metric Usage Statistics

指标使用统计

bash

undefined

bash

undefined

Which metrics are being queried, and how often

查询哪些指标被查询以及查询频率

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/metric_names_stats?limit=20" | jq .

Metrics queried <= N times (find unused/rarely-used metrics)

查询被查询次数≤N的指标（找出未使用/极少使用的指标）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/metric_names_stats?limit=50&le=1" | jq .

Filter by metric name pattern

按指标名称模式过滤

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/metric_names_stats?match_pattern=vm_&limit=20" | jq .


Parameters: `limit` (max results), `le` (max query count threshold — find metrics queried at most N times), `match_pattern` (metric name prefix filter).

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/status/metric_names_stats?match_pattern=vm_&limit=20" | jq .


参数：`limit`（最大结果数）、`le`（最大查询次数阈值——找出查询次数最多为N次的指标）、`match_pattern`（指标名称前缀过滤器）。

Flags (Non-Default)

非默认参数

bash

undefined

bash

undefined

View non-default runtime flags (returns plain text, one flag per line — NOT JSON)

查看非默认运行时参数（返回纯文本，每行一个参数——非JSON格式）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"${VM_METRICS_URL%%/select/*}/flags"


Root-level endpoint. Returns plain text (not JSON), one flag per line. Shows only flags that differ from defaults — useful for debugging configuration.

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"${VM_METRICS_URL%%/select/*}/flags"


根级端点。返回纯文本（非JSON），每行一个参数。仅显示与默认值不同的参数——有助于调试配置。

Query Tools

查询工具

These are ROOT-level endpoints, NOT under

/api/v1/

. On cluster mode, strip the

/select/0/prometheus

prefix to get the base host.

bash

undefined

这些是根级端点，不在
/api/v1/
路径下。在集群模式下，需要去掉

/select/0/prometheus

前缀以获取基础主机地址。

bash

undefined

Expand WITH expressions (returns text, not JSON)

展开WITH表达式（返回文本，非JSON）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"${VM_METRICS_URL%%/select/*}/expand-with-exprs?query=WITH(x=up)x"

Prettify MetricsQL query (returns JSON)

格式化MetricsQL查询（返回JSON）

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"${VM_METRICS_URL%%/select/*}/prettify-query?query=rate(x[5m])" | jq .


Note: `${VM_METRICS_URL%%/select/*}` strips everything from `/select` onward, yielding the base host. On single-node (local), `VM_METRICS_URL` has no `/select` prefix so it returns the URL unchanged.

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"${VM_METRICS_URL%%/select/*}/prettify-query?query=rate(x[5m])" | jq .


注意：`${VM_METRICS_URL%%/select/*}`会去掉`/select`之后的所有内容，得到基础主机地址。在单实例（本地）模式下，`VM_METRICS_URL`没有`/select`前缀，因此会直接返回原URL。

Config Debug Tools

配置调试工具

Root-level endpoints for debugging relabeling, downsampling, and retention configurations. These accept POST with form data. Primarily used via VMUI but accessible via curl.

bash

undefined

用于调试重标记、降采样和保留配置的根级端点。这些端点接受POST表单数据。主要通过VMUI使用，但也可通过curl访问。

bash

undefined

Debug metric relabeling rules — test how a metric is transformed

调试指标重标记规则——测试指标如何被转换

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
-d 'metric=foo{bar="baz"}'
-d 'relabel_config=- target_label: cluster replacement: dev'
"${VM_METRICS_URL%%/select/*}/metric-relabel-debug"

Debug downsampling filters — test which downsampling rules match a metric

调试降采样过滤器——测试哪些降采样规则匹配指标

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
-d 'metric=foo{bar="baz"}'
-d 'downsampling_period=30d:5m,180d:1h'
"${VM_METRICS_URL%%/select/*}/downsampling-filters-debug"

Debug retention filters — test which retention policy applies to a metric

调试保留过滤器——测试哪些保留策略适用于指标

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
-d 'metric=foo{bar="baz"}'
-d 'retention_period=2y,{env="dev"}:30d'
"${VM_METRICS_URL%%/select/*}/retention-filters-debug"


These return HTML by default. For programmatic use, the VMUI at `${VM_METRICS_URL%%/select/*}/vmui/#/relabeling` provides an interactive interface.

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
-d 'metric=foo{bar="baz"}'
-d 'retention_period=2y,{env="dev"}:30d'
"${VM_METRICS_URL%%/select/*}/retention-filters-debug"


这些端点默认返回HTML。如果用于编程场景，可通过VMUI的`${VM_METRICS_URL%%/select/*}/vmui/#/relabeling`界面进行交互式调试。

Timestamp Format

时间戳格式

All times accept RFC3339 (

2026-03-07T09:00:00Z

) or Unix seconds (

1709769600

). Default

time

for instant queries is "now". Default

end

for range queries is "now".

所有时间参数支持RFC3339格式（

2026-03-07T09:00:00Z

）或Unix时间戳（

1709769600

）。即时查询的默认

time

为“当前时间”。范围查询的默认

end

为“当前时间”。

Response Parsing (jq)

响应解析（jq）

bash

undefined

bash

undefined

Extract metric values from instant query

从即时查询中提取指标值

... | jq '.data.result[] | {metric: .metric.name, value: .value[1]}'

Extract time series from range query

从范围查询中提取时间序列

... | jq '.data.result[] | {metric: .metric, values: [.values[] | {time: .[0], value: .[1]}]}'

List metric names from series response

从序列响应中列出指标名称

... | jq '[.data[] | .name] | unique'

Count alerts by state

按状态统计告警数量

... | jq '.data.alerts | group_by(.state) | map({state: .[0].state, count: length})'

Top series by cardinality from tsdb status

从TSDB状态中获取基数最高的序列

... | jq '.data.seriesCountByMetricName[:10]'

undefined

... | jq '.data.seriesCountByMetricName[:10]'

undefined

Common Patterns

常见模式

bash

undefined

bash

undefined

Check if a metric exists

检查指标是否存在

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_METRICS_URL/api/v1/query?query=count({name=~"http_request.*"})" | jq '.data.result[].value[1]'

Get all namespaces with active pods

获取所有包含活跃Pod的命名空间

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'match[]={name="kube_pod_info"}'
"$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

Rate of errors over last hour

过去一小时内的错误率

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'query=sum(rate(http_requests_total{code=~"5.."}[5m])) by (namespace)'
"$VM_METRICS_URL/api/v1/query" | jq '.data.result[] | {ns: .metric.namespace, rate: .value[1]}'

undefined

curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'query=sum(rate(http_requests_total{code=~"5.."}[5m])) by (namespace)'
"$VM_METRICS_URL/api/v1/query" | jq '.data.result[] | {ns: .metric.namespace, rate: .value[1]}'

undefined

Environment Switching

环境切换

bash

undefined

bash

undefined

Check current environment

检查当前环境

echo "VM_METRICS_URL: $VM_METRICS_URL" echo "VM_AUTH_HEADER: $( [ -n "$VM_AUTH_HEADER" ] && echo '(set)' || echo '(empty)' )"

undefined

echo "VM_METRICS_URL: $VM_METRICS_URL" echo "VM_AUTH_HEADER: $( [ -n "$VM_AUTH_HEADER" ] && echo '(已设置)' || echo '(为空)' )"

undefined

Important Notes

重要注意事项

POST endpoints accept
```
application/x-www-form-urlencoded
```
(use
```
--data-urlencode
```
for query params with special chars)
```
match[]
```
parameter requires the
```
[]
```
suffix —
```
match
```
alone won't work
For metric metadata, raw API uses
```
metric
```
param

label_values

uses a path parameter:

/api/v1/label/{label_name}/values

expand-with-exprs

,

prettify-query

,

flags

,

metric-relabel-debug

,

downsampling-filters-debug

, and

retention-filters-debug

are root-level paths, not under

/api/v1/

Export endpoint (
```
/api/v1/export
```
) returns JSON lines (one object per line), not standard API response JSON
Debug endpoints (
```
metric-relabel-debug
```
, etc.) return HTML by default — best used via VMUI for interactive debugging
For full endpoint details, parameters, and response formats, see
```
references/api-reference.md
```

POST端点接受
```
application/x-www-form-urlencoded
```
格式（对于包含特殊字符的查询参数，请使用
```
--data-urlencode
```
）
```
match[]
```
参数必须包含
```
[]
```
后缀——仅使用
```
match
```
无效
指标元数据接口使用
```
metric
```
参数

label_values

使用路径参数：

/api/v1/label/{label_name}/values

expand-with-exprs

、

prettify-query

、

flags

、

metric-relabel-debug

、

downsampling-filters-debug

和

retention-filters-debug

是根级路径，不在

/api/v1/

下

导出端点（
```
/api/v1/export
```
）返回JSON行（每行一个对象），而非标准API响应JSON
调试端点（如
```
metric-relabel-debug
```
等）默认返回HTML——通过VMUI进行交互式调试体验更佳
如需完整的端点详情、参数和响应格式，请查看
```
references/api-reference.md
```

victoriametrics-query

Original

Translation

VictoriaMetrics Metrics Query

VictoriaMetrics 指标查询

Environment

环境配置

$VM_METRICS_URL - base URL

$VM_METRICS_URL - 基础URL

cluster: export VM_METRICS_URL="https://vmselect.example.com/select/0/prometheus"

集群模式: export VM_METRICS_URL="https://vmselect.example.com/select/0/prometheus"

single: export VM_METRICS_URL="http://localhost:8428"

单实例模式: export VM_METRICS_URL="http://localhost:8428"

$VM_AUTH_HEADER - auth header (set for prod, empty for local)

$VM_AUTH_HEADER - 认证头（生产环境设置，本地环境留空）

Auth Pattern

认证模式

Core Endpoints

核心端点

Instant Query

即时查询

Query at current time

查询当前时间的数据

Query at specific time

查询指定时间的数据

Range Query

范围查询

Labels Discovery

标签发现

All label names

获取所有标签名称

Label values (label_name is a PATH parameter)

获取标签值（label_name为路径参数）

Label values filtered by series matcher

通过序列匹配器过滤标签值

Series Discovery

序列发现

Find series matching selector

查找匹配选择器的序列

Metric Metadata

指标元数据

Search by metric name keyword

通过指标名称关键词搜索

Alerts and Rules

告警与规则

All firing/pending alerts

获取所有触发/待处理的告警

All alerting and recording rules

获取所有告警规则和记录规则

Instance Diagnostics

实例诊断

TSDB cardinality stats

TSDB基数统计

Currently executing queries

当前正在执行的查询

Most frequent/slowest queries

最频繁/最慢的查询

Version info

版本信息

Export Raw Data

导出原始数据

Export raw samples as JSON lines (one JSON object per line)

以JSON行格式导出原始样本（每行一个JSON对象）

Export with reduced memory usage (for large exports)

以低内存占用模式导出（适用于大规模导出）

Series Count

序列数量统计

Total number of active time series

获取活跃时间序列的总数

Metric Usage Statistics

指标使用统计

Which metrics are being queried, and how often

查询哪些指标被查询以及查询频率

Metrics queried <= N times (find unused/rarely-used metrics)

查询被查询次数≤N的指标（找出未使用/极少使用的指标）

Filter by metric name pattern

按指标名称模式过滤

Flags (Non-Default)

非默认参数

View non-default runtime flags (returns plain text, one flag per line — NOT JSON)