VictoriaMetrics

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:

CODEBLOCK0

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

2. Start Querying

CODEBLOCK1

Configuration

Config File Location

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

CODEBLOCK2

Priority order:

1. 1. Path from VICTORIAMETRICS_CONFIG environment variable
2. INLINECODE4
3. INLINECODE5
4. INLINECODE6 (current directory)
5. INLINECODE7

Config Format

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

Single-Node Deployment

CODEBLOCK3

Cluster Deployment (Multi-Tenant)

CODEBLOCK4

Fields:

• - name — unique identifier for the instance
• INLINECODE11 — "single" or "cluster" (default: "single")
• INLINECODE15 — VictoriaMetrics server URL

• - accountID — tenant account ID (cluster only, default: 0)
• INLINECODE19 — tenant project ID (cluster only, optional)
• INLINECODE20 / password — optional HTTP Basic Auth credentials
• INLINECODE22 — which instance to use when none specified

Environment Variables (Legacy)

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

CODEBLOCK5

Usage

Global Flags

Commands

Setup

CODEBLOCK6

Query Metrics

CODEBLOCK7

Common Queries

Disk space usage:
CODEBLOCK8

CPU usage:
CODEBLOCK9

Memory usage:
CODEBLOCK10

Load average:
CODEBLOCK11

GPU memory usage (NVIDIA):
CODEBLOCK12

GPU temperature:
CODEBLOCK13

List Configured Instances

CODEBLOCK14

Output:
CODEBLOCK15

Other Commands

CODEBLOCK16

Multi-Instance Output Format

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

CODEBLOCK17

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: INLINECODE28
• Suitable for ingestion rates < 1M data points per second
• Can be set up in High Availability mode

Cluster

• - Horizontal scalability
• URL format: INLINECODE29
• 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

Universal Queries (Auto-detect)

CODEBLOCK18

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

Common Queries Reference

node_exporter Metrics

categraf Metrics

GPU Metrics (DCGM)

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.