VictoriaMetrics

Query and manage VictoriaMetrics time-series database instances. Supports both single-node and cluster deployments with multi-tenancy. Use when the user asks about metrics, monitoring, PromQL queries, VictoriaMetrics, time-series data, or mentions "vmselect", "vminsert", "vmstorage", or needs to query monitoring metrics from VictoriaMetrics instances. Also use for common monitoring tasks like checking CPU usage, memory, disk space, GPU metrics, service health, or custom PromQL queries.

Query and manage VictoriaMetrics time-series database instances. Supports both single-node and cluster deployments with multi-tenancy.

Security Notice

This skill requires the following permissions for legitimate functionality:

• HTTP/HTTPS requests: Query VictoriaMetrics API endpoints
• File system access: Read configuration files (victoriametrics.json)
• Base64 encoding: HTTP Basic Authentication for secure API access

All network operations are user-initiated and only connect to user-configured VictoriaMetrics instances. No data is sent to external services.

Quick Start

1. Initial Setup

Run the interactive configuration wizard:

bash

cd ~/.openclaw/workspace/skills/victoriametrics
node scripts/cli.js init

This will create a victoriametrics.json config file in your OpenClaw workspace (~/.openclaw/workspace/victoriametrics.json).

2. Start Querying

bash

# Query default instance
node scripts/cli.js query 'up'

# Query all instances at once
node scripts/cli.js query 'up' --all

# List configured instances
node scripts/cli.js instances

Configuration

Config File Location

By default, the skill looks for config in your OpenClaw workspace:

text

~/.openclaw/workspace/victoriametrics.json

Priority order:

1. Path from VICTORIAMETRICS_CONFIG environment variable
2. ~/.openclaw/workspace/victoriametrics.json
3. ~/.openclaw/workspace/config/victoriametrics.json
4. ./victoriametrics.json (current directory)
5. ~/.config/victoriametrics/config.json

Config Format

Create victoriametrics.json in your workspace (or use node cli.js init):

Single-Node Deployment

json

{
  "instances": [
    {
      "name": "production",
      "type": "single",
      "url": "http://victoriametrics:8428",
      "user": "admin",
      "password": "secret"
    }
  ],
  "default": "production"
}

Cluster Deployment (Multi-Tenant)

json

{
  "instances": [
    {
      "name": "cluster-prod",
      "type": "cluster",
      "url": "http://vmselect:8481",
      "accountID": 0,
      "user": "admin",
      "password": "secret"
    },
    {
      "name": "cluster-tenant42",
      "type": "cluster",
      "url": "http://vmselect:8481",
      "accountID": 42,
      "projectID": 9
    }
  ],
  "default": "cluster-prod"
}

Fields:

• name — unique identifier for the instance
• type — "single" or "cluster" (default: "single")
• url — VictoriaMetrics server URL
  • Single-node: http://victoriametrics:8428
  • Cluster: http://vmselect:8481
• accountID — tenant account ID (cluster only, default: 0)
• projectID — tenant project ID (cluster only, optional)
• user / password — optional HTTP Basic Auth credentials
• default — which instance to use when none specified

Environment Variables (Legacy)

For single-instance setups, you can use environment variables:

bash

export VICTORIAMETRICS_URL=http://victoriametrics:8428
export VICTORIAMETRICS_USER=admin
export VICTORIAMETRICS_PASSWORD=secret

Usage

Global Flags

Flag	Description
-c, --config <path>	Path to config file
-i, --instance <name>	Target specific instance
-a, --all	Query all configured instances

Commands

Setup

bash

# Interactive configuration wizard
node scripts/cli.js init

Query Metrics

bash

cd ~/.openclaw/workspace/skills/victoriametrics

# Query default instance
node scripts/cli.js query 'up'

# Query specific instance
node scripts/cli.js query 'up' -i cluster-prod

# Query ALL instances at once
node scripts/cli.js query 'up' --all

# Custom config file
node scripts/cli.js query 'up' -c /path/to/config.json

Common Queries

Disk space usage:

bash

node scripts/cli.js query '100 - (node_filesystem_avail_bytes / node_filesystem_size_bytes * 100)' --all

CPU usage:

bash

node scripts/cli.js query '100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)' --all

Memory usage:

bash

node scripts/cli.js query '(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100' --all

Load average:

bash

node scripts/cli.js query 'node_load1' --all

GPU memory usage (NVIDIA):

bash

node scripts/cli.js query 'nvidia_gpu_memory_used_bytes / nvidia_gpu_memory_total_bytes * 100' --all

GPU temperature:

bash

node scripts/cli.js query 'nvidia_gpu_temperature_celsius' --all

List Configured Instances

bash

node scripts/cli.js instances

Output:

json

{
  "default": "cluster-prod",
  "instances": [
    {
      "name": "cluster-prod",
      "type": "cluster",
      "url": "http://vmselect:8481",
      "accountID": 0,
      "hasAuth": true
    },
    {
      "name": "single-dev",
      "type": "single",
      "url": "http://localhost:8428",
      "hasAuth": false
    }
  ]
}

Other Commands

bash

# List all metrics matching pattern
node scripts/cli.js metrics 'node_memory_*'

# Get label names
node scripts/cli.js labels --all

# Get values for a label
node scripts/cli.js label-values instance --all

# Find time series
node scripts/cli.js series '{__name__=~"node_cpu_.*", instance=~".*:9100"}' --all

# Get active alerts
node scripts/cli.js alerts --all

# Check instance health
node scripts/cli.js health -i cluster-prod

Multi-Instance Output Format

When using --all, results include data from all instances:

json

{
  "resultType": "vector",
  "results": [
    {
      "instance": "cluster-prod",
      "status": "success",
      "resultType": "vector",
      "result": [...]
    },
    {
      "instance": "single-dev",
      "status": "success",
      "resultType": "vector",
      "result": [...]
    }
  ]
}

Errors on individual instances don't fail the entire query — they appear with "status": "error" in the results array.

Deployment Types

Single-Node

• Simpler setup and operation
• URL format: http://<victoriametrics>:8428/api/v1/query
• Suitable for ingestion rates < 1M data points per second
• Can be set up in High Availability mode

Cluster

• Horizontal scalability
• URL format: http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query
• Multi-tenancy support via accountID and projectID
• Components: vmstorage, vminsert, vmselect
• Each component scales independently

Supported Metric Collectors

This skill supports multiple metric collection agents:

• node_exporter - Standard Prometheus node exporter
• categraf - Flashcat's telemetry collector
• DCGM - NVIDIA GPU metrics
• Custom exporters - Any Prometheus-compatible exporter

Quick Comparison

Metric Type	node_exporter	categraf
CPU Usage	100 - avg(irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100	cpu_usage_active{cpu="cpu-total"}
Memory Usage	(1 - node_memory_MemAvailable_bytes/node_memory_MemTotal_bytes) * 100	mem_used_percent
Disk Usage	100 - (node_filesystem_avail_bytes/node_filesystem_size_bytes * 100)	disk_used_percent
System Load	node_load1	system_load1

Universal Queries (Auto-detect)

bash

# CPU usage (works with both node_exporter and categraf)
node scripts/cli.js query 'cpu_usage_active{cpu="cpu-total"} or (100 - (avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100))'

# Memory usage (works with both)
node scripts/cli.js query 'mem_used_percent or ((node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100)'

# Disk usage (works with both)
node scripts/cli.js query 'disk_used_percent or (100 - (node_filesystem_avail_bytes / node_filesystem_size_bytes * 100))'

For complete query examples for all metric types, see references/common_queries.md.

Common Queries Reference

node_exporter Metrics

Metric	PromQL Query
Disk free %	node_filesystem_avail_bytes / node_filesystem_size_bytes * 100
Disk used %	100 - (node_filesystem_avail_bytes / node_filesystem_size_bytes * 100)
CPU idle %	avg by (instance) (irate(node_cpu_seconds_total{mode="idle"}[5m])) * 100
Memory used %	(node_memory_MemTotal_bytes - node_memory_MemAvailable_bytes) / node_memory_MemTotal_bytes * 100
Network RX	rate(node_network_receive_bytes_total[5m])
Network TX	rate(node_network_transmit_bytes_total[5m])
Uptime	node_time_seconds - node_boot_time_seconds
Service up	up

categraf Metrics

Metric	PromQL Query
CPU usage %	cpu_usage_active{cpu="cpu-total"}
Memory used %	mem_used_percent
Disk used %	disk_used_percent
Network RX	rate(net_bytes_recv[5m])
Network TX	rate(net_bytes_sent[5m])
System load 1m	system_load1
System uptime	system_uptime

GPU Metrics (DCGM)

Metric	PromQL Query
GPU memory used %	DCGM_FI_DEV_FB_USED / (DCGM_FI_DEV_FB_FREE + DCGM_FI_DEV_FB_USED) * 100
GPU temperature	DCGM_FI_DEV_GPU_TEMP
GPU utilization	DCGM_FI_DEV_GPU_UTIL
GPU power usage	DCGM_FI_DEV_POWER_USAGE

Notes

• Time range defaults to last 1 hour for instant queries
• Use range queries [5m] for rate calculations
• All queries return JSON with data.result containing the results
• Instance labels typically show host:port format
• When using --all, queries run in parallel for faster results
• Config is stored outside the skill directory so it persists across skill updates
• For cluster deployments, the accountID and projectID are automatically inserted into the URL path

VictoriaMetrics API Differences

VictoriaMetrics is compatible with Prometheus API but includes additional features:

• MetricsQL: Extended PromQL with additional functions
• Multi-tenancy: Native support in cluster mode
• High cardinality: Better performance with many time series
• Storage efficiency: Better compression than Prometheus

For detailed API documentation, see references/api_reference.md.