VictoriaMetrics queries

v0.1.14

Read-only PromQL / MetricsQL access to VictoriaMetrics over its HTTP API: instant and range queries, series and label discovery, and the VM-specific status endpoints (TSDB cardinality, active queries, top queries). One base URL serves single-node, cluster (vmselect), and vmauth-fronted deployments.

8 allowed by default

Pack ID

victoriametrics

Vendor

emisar

linux

Actions

Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.


              curl

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host

sudo emisar pack install victoriametrics --hash sha256:3445aabac68dc20cef2930dd7f123fddfac479ea7c92f4589ae080b7dfed2087

Setup

Every action calls the VictoriaMetrics HTTP API at $VM_URL via curl on the runner host. Point VM_URL at the query base URL including any /prometheus (single-node) or /select/<accountID>/prometheus (cluster) prefix; each action appends /api/v1/.... Set VM_BEARER_TOKEN if the endpoint sits behind vmauth or another bearer-token proxy.

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

VM_URL default http://127.0.0.1:8428

Query base URL — scheme, host, port, and the prefix up to (but not including) /api/v1. Single-node ends in /prometheus; cluster reads go through vmselect at /select/<accountID>/prometheus.
VM_BEARER_TOKEN

Optional bearer token for vmauth-protected endpoints. Sent as "Authorization: Bearer <token>" over curl stdin, so it never appears in the process arguments or the audit log.

Notes

Any of VM_URL / VM_BEARER_TOKEN you set must also be allowlisted in the runner's execution.inherit_env — the action env is scrubbed to PATH/LANG/LC_ALL/TERM by default, so an env present on the host but not allowlisted is silently dropped (the action falls back to its local default or fails auth).
Single-node URL: http://<host>:8428/prometheus. Cluster (vmselect) reads: http://<vmselect>:8481/select/<accountID>/prometheus. Behind vmauth: use its base URL plus whatever route prefix maps to the backend.
Every action is a read-only GET — none write, delete, or mutate series. Range queries are limited to 7 days and 10,081 outer evaluation timestamps per returned series, with a 30-second provider-side timeout. This preserves a full week at one-minute resolution; query cardinality, range-vector lookbacks, and subqueries can still add cost.
No token is sent unless VM_BEARER_TOKEN is set. For basic-auth fronts, embed credentials in VM_URL (http://user:pass@host) or terminate auth at a trusted side door.

Verify it works

Runs vm.labels, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host

sudo emisar pack verify victoriametrics

Install and configure a pack walks through the whole sequence on a host.

Actions 8 total

View on GitHub

vm.active_queries script low

GET /api/v1/status/active_queries

List the queries VictoriaMetrics is executing right now — their text, how long they have been running, and the client address. Use to catch a runaway or slow query in the act.
View source on GitHub
vm.label_values script low

GET /api/v1/label/<name>/values

List all values for one label. Use to enumerate jobs, instances, or any other dimension before filtering a query.
View source on GitHub
vm.labels script low

GET /api/v1/labels

List every label name present in VictoriaMetrics over the default time range. Use to discover the available dimensions. Doubles as the pack's connectivity check.
View source on GitHub
vm.query_instant script low

GET /api/v1/query

Run an instant PromQL/MetricsQL query against VictoriaMetrics — evaluates one expression at the current time. Use to answer "what is X right now?" and use vm.query_range when the trend over a window matters. An empty result means no matching time series at this evaluation time; discover labels or correct the selector instead of repeating the same query.
View source on GitHub
vm.query_range script low

GET /api/v1/query_range

Run a range PromQL/MetricsQL query against VictoriaMetrics — evaluates one expression across a trailing window ending now, bounded by the server's retention and by 10,081 outer evaluation timestamps per returned series; the server enforces its own points and query-duration limits. Use for trends and rates over time; use vm.query_instant for a single current value. A successful range response can legitimately contain no matching series, so refine or discover the selector instead of repeating an unchanged query. Query cardinality and inner ranges can still make this expensive.
View source on GitHub
vm.series script low

GET /api/v1/series

List the time series matching a selector — the label sets that exist, not their samples. Use to discover what is stored before writing a query.
View source on GitHub
vm.top_queries script low

GET /api/v1/status/top_queries

List the most frequent and most expensive queries VictoriaMetrics has seen — topByCount, topByAvgDuration, and topBySumDuration. Use to find what to optimize or rate-limit.
View source on GitHub
vm.tsdb_status script low

GET /api/v1/status/tsdb

Show TSDB cardinality stats — the metric names, label pairs, and label values with the highest series counts. The first stop when cardinality or memory is climbing.
View source on GitHub

← Back to registry

Pack reference Publish your own