Commands & Recipes

Installation

Docker (Quick Start — All Components)

# VictoriaMetrics (metrics)
docker run -d --name vm \
  -p 8428:8428 \
  -v vm-data:/storage \
  victoriametrics/victoria-metrics \
  -storageDataPath=/storage -retentionPeriod=12

# VictoriaLogs (logs)
docker run -d --name vl \
  -p 9428:9428 \
  -v vl-data:/vlogs \
  victoriametrics/victoria-logs \
  -storageDataPath=/vlogs -retentionPeriod=30d

# VictoriaTraces (traces)
docker run -d --name vt \
  -p 10428:10428 \
  -p 4317:4317 \
  -v vt-data:/vtraces \
  victoriametrics/victoria-traces \
  -storageDataPath=/vtraces

Docker Compose (Full Stack)

# docker-compose.yaml — Full Victoria stack for development
version: '3.8'
services:
  victoriametrics:
    image: victoriametrics/victoria-metrics:latest
    ports: ["8428:8428"]
    volumes: ["vm-data:/storage"]
    command:
      - "-storageDataPath=/storage"
      - "-retentionPeriod=12"

  victorialogs:
    image: victoriametrics/victoria-logs:latest
    ports: ["9428:9428"]
    volumes: ["vl-data:/vlogs"]
    command:
      - "-storageDataPath=/vlogs"
      - "-retentionPeriod=30d"

  victoriatraces:
    image: victoriametrics/victoria-traces:latest
    ports:
      - "10428:10428"  # HTTP
      - "4317:4317"    # OTLP gRPC
    volumes: ["vt-data:/vtraces"]
    command:
      - "-storageDataPath=/vtraces"

  vmagent:
    image: victoriametrics/vmagent:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - "-promscrape.config=/etc/prometheus/prometheus.yml"
      - "-remoteWrite.url=http://victoriametrics:8428/api/v1/write"

  vmauth:
    image: victoriametrics/vmauth:latest
    ports: ["8427:8427"]
    volumes:
      - ./vmauth-config.yml:/etc/vmauth/config.yml
    command:
      - "-auth.config=/etc/vmauth/config.yml"

  vmalert:
    image: victoriametrics/vmalert:latest
    volumes:
      - ./alert-rules.yml:/etc/rules/rules.yml
    command:
      - "-rule=/etc/rules/*.yml"
      - "-datasource.url=http://victoriametrics:8428"
      - "-remoteWrite.url=http://victoriametrics:8428"

  grafana:
    image: grafana/grafana-oss:latest
    ports: ["3000:3000"]
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

volumes:
  vm-data:
  vl-data:
  vt-data:

Helm (Kubernetes)

helm repo add vm https://victoriametrics.github.io/helm-charts/
helm repo update

# Single-node VictoriaMetrics
helm install vm vm/victoria-metrics-single -n monitoring --create-namespace

# Cluster VictoriaMetrics
helm install vm-cluster vm/victoria-metrics-cluster -n monitoring -f vm-values.yaml

# vmoperator (manages all components via CRDs)
helm install vmoperator vm/victoria-metrics-operator -n monitoring

# vmagent
helm install vmagent vm/victoria-metrics-agent -n monitoring

# vmalert
helm install vmalert vm/victoria-metrics-alert -n monitoring

# VictoriaLogs (single-node)
helm install vl vm/victoria-logs-single -n monitoring

vmagent Recipes

# Start vmagent as drop-in Prometheus replacement
./vmagent \
  -promscrape.config=/path/to/prometheus.yml \
  -remoteWrite.url=http://victoriametrics:8428/api/v1/write

# Add global labels to all scraped metrics
./vmagent \
  -remoteWrite.label=datacenter=us-east-1 \
  -remoteWrite.label=env=production \
  -promscrape.config=prometheus.yml \
  -remoteWrite.url=http://vminsert:8480/insert/0/prometheus/api/v1/write

# Multi-destination remote write (fan-out)
./vmagent \
  -remoteWrite.url=http://vm-primary:8428/api/v1/write \
  -remoteWrite.url=http://vm-secondary:8428/api/v1/write

Data Ingestion Recipes

Fluent Bit → VictoriaLogs

# fluent-bit.conf — Push logs directly to VictoriaLogs
[OUTPUT]
    Name  http
    Match *
    Host  victorialogs
    Port  9428
    URI   /insert/jsonline?_stream_fields=stream&_msg_field=log&_time_field=date
    Format json_lines
    Compress gzip

OpenTelemetry Collector → VictoriaTraces

# otel-collector-config.yaml
exporters:
  otlp/victoriatraces:
    endpoint: "victoriatraces:4317"
    tls:
      insecure: true

  prometheusremotewrite/vm:
    endpoint: "http://victoriametrics:8428/api/v1/write"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/victoriatraces]
    metrics:
      receivers: [otlp, prometheus]
      processors: [batch]
      exporters: [prometheusremotewrite/vm]

Promtail / Loki Push → VictoriaLogs

# promtail-config.yaml — VictoriaLogs accepts Loki push API
clients:
  - url: http://victorialogs:9428/insert/loki/api/v1/push

Direct OTLP → VictoriaTraces

• HTTP: http://victoriatraces:10428/insert/opentelemetry/v1/traces
• gRPC: grpc://victoriatraces:4317

vmauth Routing Config

# vmauth-config.yml — Route all signals through one proxy
unauthorized_user:
  url_map:
    # Metrics write
    - src_paths: ["/api/v1/write", "/api/v1/import.*"]
      url_prefix: "http://vminsert:8480/insert/0/prometheus"

    # Metrics read
    - src_paths: ["/api/v1/query.*", "/api/v1/series.*", "/api/v1/labels.*"]
      url_prefix: "http://vmselect:8481/select/0/prometheus"

    # Logs write
    - src_paths: ["/insert/jsonline.*", "/insert/elasticsearch.*", "/loki/api/v1/push"]
      url_prefix: "http://victorialogs:9428"

    # Logs read
    - src_paths: ["/select/logsql/.*"]
      url_prefix: "http://victorialogs:9428"

    # Traces write
    - src_paths: ["/insert/opentelemetry/.*"]
      url_prefix: "http://victoriatraces:10428"

    # Traces read (Jaeger API)
    - src_paths: ["/api/traces.*", "/api/services.*"]
      url_prefix: "http://victoriatraces:10428"

Backup & Restore

# Create instant snapshot (single-node)
curl http://victoriametrics:8428/snapshot/create
# Returns: {"status":"ok","snapshot":"20260410120000-..."}

# Backup snapshot to S3
./vmbackup \
  -storageDataPath=/data/vm \
  -snapshot.createURL=http://localhost:8428/snapshot/create \
  -dst=s3://my-bucket/vm-backups/

# Incremental backup (only new data since last backup)
./vmbackup \
  -storageDataPath=/data/vm \
  -snapshot.createURL=http://localhost:8428/snapshot/create \
  -dst=s3://my-bucket/vm-backups/ \
  -origin=s3://my-bucket/vm-backups/  # previous backup path

# Restore from backup
./vmrestore \
  -src=s3://my-bucket/vm-backups/latest \
  -storageDataPath=/data/vm-restored

Note: For clustered setup, vmbackup must be executed on EVERY vmstorage node.

API Recipes

# Query VictoriaMetrics (PromQL/MetricsQL)
curl -s "http://vm:8428/api/v1/query?query=up" | jq .

# Range query
curl -s "http://vm:8428/api/v1/query_range?query=rate(http_requests_total[5m])&start=-1h&step=60s" | jq .

# Import data via JSON
curl -d '{"metric":{"__name__":"test","job":"api"},"values":[1,2,3],"timestamps":[1617000000000,1617000001000,1617000002000]}' \
  http://vm:8428/api/v1/import

# Query VictoriaLogs (LogsQL)
curl -s "http://vl:9428/select/logsql/query?query=_time:5m+AND+error" | jq .

# Push a test log
curl -X POST "http://vl:9428/insert/jsonline?_stream_fields=app&_msg_field=msg" \
  -d '{"app":"test","msg":"hello from curl","level":"info"}'

# Look up a trace by ID (Jaeger API)
curl -s "http://vt:10428/api/traces/abc123" | jq .

# Check health
curl -s "http://vm:8428/-/healthy" && echo "OK"

Grafana Data Source Config

# Grafana provisioning for Victoria Stack
apiVersion: 1
datasources:
  - name: VictoriaMetrics
    type: prometheus
    url: http://vmauth:8427
    isDefault: true
    jsonData:
      httpMethod: POST

  - name: VictoriaLogs
    type: victoriametrics-logs-datasource
    url: http://vmauth:8427

  - name: VictoriaTraces
    type: jaeger
    url: http://vmauth:8427

Related Notes

• Operations
• Architecture