VictoriaMetrics

Query and manage VictoriaMetrics time-series database instances. Supports both single-node and cluster deployments with multi-tenancy. Use when the user asks...

Security Scan

The skill is internally consistent with a VictoriaMetrics CLI: it reads/writes a local config, makes HTTP(S) requests to user-configured VictoriaMetrics endpoints, and uses HTTP Basic/Bearer auth as documented.

Purpose & Capability

The skill's name, description, SKILL.md, reference docs, and included CLI implementation all align: this is a CLI for querying/managing VictoriaMetrics. Minor gap: the runtime instructions assume Node (invoke via `node scripts/cli.js`) but the registry metadata lists no required binaries/dependencies. Declaring Node.js as a required binary would be expected.

Instruction Scope

Runtime instructions and the CLI implementation stay within scope: they read a local config file, prompt for credentials, and make HTTP(S) requests to the user-provided VictoriaMetrics endpoints. There are no instructions to read unrelated system files, enumerate other services, or transmit data to unexpected external endpoints.

Install Mechanism

No install spec is provided (instruction-only with an included script). The code is shipped in the skill and will run when the user invokes the CLI with Node. There are no downloads from external URLs or archive extraction steps in the install metadata.

Credentials

The skill does not require any declared environment variables or secrets in registry metadata. It documents optional legacy env vars (VICTORIAMETRICS_URL, _USER, _PASSWORD) and supports per-instance credentials stored in the local config. The variables and file access it requests are proportional to its purpose.

Persistence & Privilege

always:false and the skill does not request permanent platform-wide privileges. It writes its own config file under the user's workspace (~/.openclaw/workspace/victoriametrics.json) which is expected behavior for a CLI; it does not attempt to modify other skills or global agent settings.

Assessment

This skill implements a local CLI that reads/writes a config file in your OpenClaw workspace and makes HTTP(S) requests to the VictoriaMetrics endpoints you configure. Before installing: (1) Be sure you have Node.js available (the SKILL.md uses `node scripts/cli.js`) — the skill metadata does not declare this dependency. (2) Store only credentials you trust in the config file; the CLI will save any username/password you enter to ~/.openclaw/workspace/victoriametrics.json by default. (3) Network calls go to the URLs you configure — do not point them to untrusted external endpoints. (4) If you need least privilege, consider running the tool in an environment with restricted network access or using instance-scoped credentials rather than exposing broad secrets. Overall the files and instructions are coherent with the stated purpose.

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:

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

# 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:

~/.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

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

Cluster Deployment (Multi-Tenant)

{
  "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:

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

# Interactive configuration wizard
node scripts/cli.js init

Query Metrics

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:

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

CPU usage:

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

Memory usage:

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

Load average:

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

GPU memory usage (NVIDIA):

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

GPU temperature:

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

List Configured Instances

node scripts/cli.js instances

Output:

{
  "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

# 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:

{
  "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)

# 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.