victoriametrics-query

VictoriaMetrics 指标查询

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

环境

# $VM_METRICS_URL - base URL
#   cluster: export VM_METRICS_URL="https://vmselect.example.com/select/0/prometheus"
#   single: export VM_METRICS_URL="http://localhost:8428"
# $VM_CURL_CONFIG - curl config file with auth header (set for remote, unset for local)
#   Remote: export VM_CURL_CONFIG="$HOME/.config/victoriametrics/curl.conf"
#   Local:  leave unset (defaults to /dev/null - no auth)

身份验证模式

所有 curl 命令都从 curl 配置文件加载身份验证信息，远程和本地环境均适用：

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s "$VM_METRICS_URL/api/v1/query?query=up" | jq .

如果未设置 VM_CURL_CONFIG，curl 会读取 /dev/null，且不会发送身份验证标头。如果已设置，该变量必须指向权限为 0600 的 curl 配置文件，其中包含 header = "Authorization: Bearer <token>"。切勿打印其内容。

核心端点

即时查询

# Query at current time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/query?query=up" | jq .

# Query at specific time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/query?query=up&time=2026-03-07T09:00:00Z" | jq .

参数：query（必填）、time（可选，RFC3339 或 Unix 秒）、step、timeout

范围查询

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$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 秒。

标签发现

# All label names
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/labels" | jq '.data[]'

# Label values (label_name is a PATH parameter)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

# Label values filtered by series matcher
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'match[]={job="kubelet"}' \
  "$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

时间序列发现

# Find series matching selector
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'match[]={namespace="myapp"}' \
  "$VM_METRICS_URL/api/v1/series?limit=20" | jq '.data[].__name__'

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

指标元数据

# Search by metric name keyword
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/metadata?metric=http_request&limit=10" | jq .

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

告警和规则

# All firing/pending alerts
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/alerts" | jq '.data.alerts[]'

# All alerting and recording rules
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/rules" | jq '.data.groups[]'

实例诊断

# TSDB cardinality stats
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/tsdb" | jq .

# Currently executing queries
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/active_queries" | jq .

# Most frequent/slowest queries
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/top_queries?topN=10" | jq .

# Version info
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/buildinfo" | jq .

导出原始数据

# Export raw samples as JSON lines (one JSON object per line)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --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 -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --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 导入）。

时间序列数量

# Total number of active time series
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/series/count" | jq .

注意：在大型数据库上可能运行缓慢，返回值也可能略高。

指标使用统计

# Which metrics are being queried, and how often
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?limit=20" | jq .

# Metrics queried <= N times (find unused/rarely-used metrics)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?limit=50&le=1" | jq .

# Filter by metric name pattern
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?match_pattern=vm_&limit=20" | jq .

参数：limit（最大结果数）、le（最大查询次数阈值——查找查询次数不超过 N 次的指标）、match_pattern（指标名称前缀筛选条件）。

标志（非默认值）

# View non-default runtime flags (returns plain text, one flag per line — NOT JSON)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "${VM_METRICS_URL%%/select/*}/flags"

根级端点。返回纯文本（非 JSON），每行一个标志。仅显示与默认值不同的标志，可用于调试配置。

查询工具

这些是根级端点，不在 /api/v1/ 下。在集群模式下，去掉 /select/0/prometheus 前缀即可获取基础主机地址。

# Expand WITH expressions (returns text, not JSON)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "${VM_METRICS_URL%%/select/*}/expand-with-exprs?query=WITH(x=up)x"

# Prettify MetricsQL query (returns JSON)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "${VM_METRICS_URL%%/select/*}/prettify-query?query=rate(x[5m])" | jq .

注意：${VM_METRICS_URL%%/select/*} 会去掉 /select 及其后面的所有内容，从而得到基础主机地址。在单节点（本地）模式下，VM_METRICS_URL 不含 /select 前缀，因此会原样返回 URL。

配置调试工具

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

# Debug metric relabeling rules — test how a metric is transformed
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  -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 -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  -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 -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  -d 'metric=foo{bar="baz"}' \
  -d 'retention_period=2y,{env="dev"}:30d' \
  "${VM_METRICS_URL%%/select/*}/retention-filters-debug"

这些端点默认返回 HTML。以编程方式使用时，可通过 ${VM_METRICS_URL%%/select/*}/vmui/#/relabeling 访问 VMUI 的交互式界面。

时间戳格式

所有时间均接受 RFC3339 格式（2026-03-07T09:00:00Z）或 Unix 秒（1709769600）。即时查询的默认 time 为“现在”。范围查询的默认 end 为“现在”。

响应解析（jq）

# 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
... | jq '.data.seriesCountByMetricName[:10]'

常见模式

# Check if a metric exists
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/query?query=count({__name__=~\"http_request.*\"})" | jq '.data.result[].value[1]'

# Get all namespaces with active pods
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'match[]={__name__="kube_pod_info"}' \
  "$VM_METRICS_URL/api/v1/label/namespace/values" | jq '.data[]'

# Rate of errors over last hour
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --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]}'

环境切换

# Check current environment
echo "VM_METRICS_URL: $VM_METRICS_URL"
echo "VM_CURL_CONFIG: ${VM_CURL_CONFIG:-(unset - no auth)}"

重要说明

• POST 端点接受 application/x-www-form-urlencoded（对于包含特殊字符的查询参数，请使用 --data-urlencode）
• match[] 参数必须包含 [] 后缀；单独使用 match 无效
• 对于指标元数据，原始 API 使用 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