obz-vm: VictoriaMetrics Provider

Quick Reference

Field	Value
Aliases	vm, victoriametrics
Signal	Metric
Query language	MetricsQL (PromQL superset)
Auth	Bearer token, Basic auth, or none
Provider flags	None
Supported cmds	query, list, info, labels, label-values, series

Supported Commands

All six core metric commands work with this provider:

obz metric query        # Run an instant or range MetricsQL query
obz metric list         # List available metric names
obz metric info         # Show metadata for a specific metric
obz metric labels       # List all known label names
obz metric label-values # List values for a given label
obz metric series       # List matching time series

Authentication

Configure auth in config.yaml under providers.<name>.auth. Supports bearer token, basic auth, or no auth.

# config.yaml
providers:
  vm:
    endpoint: http://localhost:8428
    auth:
      token: ${env:VM_TOKEN}

Then query with just -p:

obz metric query -p vm -q 'up'

MetricsQL Guide

MetricsQL is fully compatible with PromQL and adds useful extensions.

Standard PromQL (works as-is)

rate(http_requests_total[5m])
sum by (job) (up)
histogram_quantile(0.99, rate(http_duration_seconds_bucket[5m]))

MetricsQL Extensions

keep_metric_names preserves the original metric name through functions that normally drop it:

rate(http_requests_total[5m]) keep_metric_names

label_set adds or overrides labels in results:

label_set(up, "env", "production")

range_normalize scales values to a 0..1 range across the time window:

range_normalize(cpu_usage_percent)

default fills gaps with a fallback value:

absent_over_time(up[5m]) default 0

Day/week suffixes: MetricsQL supports d for days and w for weeks, which standard PromQL doesn't:

avg_over_time(cpu_idle[7d])

Subquery shorthand with trailing [range:step]:

max_over_time(rate(errors_total[5m])[1h:1m])

Common Pitfalls

• MetricsQL auto-aligns [range] to the query step. If you see unexpected smoothing, set an explicit step with --step.
• keep_metric_names only works on functions returning a single series per input series. Aggregations like sum() ignore it.
• Label filters are case-sensitive. {job="API"} won't match job="api".

Examples

Instant query:

obz metric query -p vm -q 'rate(http_requests_total[5m])' --from now-1h

Range query, 5m step:

obz metric query -p vm -q 'avg by (instance) (node_cpu_seconds_total)' \
  --from now-1d --to now --step 5m

List metric names matching a prefix:

obz metric list -p vm --match 'http_*'

Get metadata for a metric:

obz metric info -p vm http_requests_total

List all label names:

obz metric labels -p vm

List values of a specific label:

obz metric label-values -p vm job

Find series matching a selector:

obz metric series -p vm --match '{job="api", env="prod"}'