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 を読み込み、認証ヘッダーを送信しません。設定されている場合は、header = "Authorization: Bearer <token>" を含むモード 0600 の curl 設定ファイルを指定する必要があります。内容を表示しないでください。

主なエンドポイント

インスタントクエリ

# 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 Lines 形式です（標準 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 ではありません）を返し、フラグを 1 行に 1 つずつ表示します。デフォルトと異なるフラグのみを表示するため、設定のデバッグに役立ちます。

クエリツール

これらはルートレベルのエンドポイントであり、/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 だけでは動作しません
• メトリクスのメタデータでは、raw 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 Lines 形式（1 行につき 1 オブジェクト）を返し、標準 API レスポンスの JSON ではありません
• デバッグエンドポイント（metric-relabel-debug など）はデフォルトで HTML を返します。対話型のデバッグには VMUI の使用が最適です
• エンドポイントの詳細、パラメーター、レスポンス形式については、references/api-reference.md を参照してください