# VictoriaMetrics

> Fast and cost-effective time-series database and monitoring solution.

- Category: Monitoring & Observability
- Difficulty: intermediate
- Components: victoriametrics, grafana
- Tags: victoriametrics, time-series, prometheus-compatible, metrics
- Source: https://docker.recipes/monitoring/victoria-metrics

## Overview

VictoriaMetrics is a high-performance, cost-effective time-series database designed as a drop-in replacement for Prometheus with significantly better resource efficiency and query performance. Originally developed by VictoriaMetrics team in 2019, it offers full Prometheus compatibility while consuming up to 10x less RAM and providing faster query execution through its optimized storage engine and MetricsQL query language that extends PromQL capabilities.

This deployment combines VictoriaMetrics as the core time-series database with Grafana as the visualization frontend. The VictoriaMetrics container runs as a single-node instance configured with 90-day data retention and exposes the Prometheus-compatible API on port 8428, while Grafana connects to it as a Prometheus data source for creating dashboards and visualizations. The two services communicate over a dedicated Docker network with persistent storage for both metrics data and Grafana configurations.

This stack is ideal for organizations seeking a more efficient alternative to traditional Prometheus setups, particularly those dealing with high-cardinality metrics or resource-constrained environments. The combination provides enterprise-grade monitoring capabilities with lower operational overhead, making it perfect for startups scaling their monitoring infrastructure, enterprises looking to reduce monitoring costs, or developers who need powerful time-series analytics without the complexity of managing multiple Prometheus instances and federation.

## Features

- Prometheus-compatible ingestion and querying API for seamless migration from existing Prometheus setups
- MetricsQL query language with extended functions beyond standard PromQL for advanced analytics
- Ultra-efficient storage engine consuming up to 10x less RAM than Prometheus with faster query performance
- 90-day configurable data retention with efficient compression and deduplication
- Native support for high-cardinality metrics without performance degradation
- Grafana integration with pre-configured Prometheus data source connection
- Single-node deployment suitable for millions of active time series
- Built-in HTTP API for both Prometheus remote_write protocol and direct metric ingestion

## Use cases

- Infrastructure monitoring replacement for resource-constrained Prometheus deployments
- High-cardinality application metrics storage for microservices architectures
- Cost-effective monitoring solution for cloud environments with usage-based pricing
- Long-term metrics retention and historical analysis for capacity planning
- IoT and sensor data collection with high ingestion rates and efficient storage
- Multi-tenant monitoring environments requiring efficient resource utilization
- Development and testing environments needing production-like monitoring capabilities

## Prerequisites

- Docker and Docker Compose installed with at least 1GB available RAM for VictoriaMetrics
- Understanding of Prometheus metrics format and PromQL query language basics
- GRAFANA_PASSWORD environment variable set for Grafana admin authentication
- Available ports 3000 (Grafana) and 8428 (VictoriaMetrics) on the host system
- Basic knowledge of time-series concepts and monitoring dashboard creation
- Sufficient disk space for metrics retention (estimate based on ingestion rate and 90-day retention)

## docker-compose.yml

```yaml
services:
  victoriametrics:
    image: victoriametrics/victoria-metrics:latest
    container_name: victoriametrics
    restart: unless-stopped
    command:
      - --storageDataPath=/data
      - --httpListenAddr=:8428
      - --retentionPeriod=90d
    volumes:
      - vm_data:/data
    ports:
      - "8428:8428"
    networks:
      - vm-network

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3000:3000"
    depends_on:
      - victoriametrics
    networks:
      - vm-network

volumes:
  vm_data:
  grafana_data:

networks:
  vm-network:
    driver: bridge
```

## .env

```bash
GRAFANA_PASSWORD=admin
```

## Usage notes

- Docs: https://docs.victoriametrics.com/
- Prometheus-compatible API at http://localhost:8428
- Use as Prometheus remote_write target or standalone
- 10x less RAM, faster queries than Prometheus
- MetricsQL extends PromQL with additional functions
- Grafana datasource: add as Prometheus type, URL http://victoriametrics:8428

## Troubleshooting

- VictoriaMetrics container exits with storage permission errors: Ensure Docker has write access to the vm_data volume mount point
- Grafana shows 'Bad Gateway' when connecting to VictoriaMetrics: Verify both containers are on vm-network and VictoriaMetrics is healthy on port 8428
- High memory usage despite VictoriaMetrics efficiency claims: Check for extremely high-cardinality metrics or inefficient MetricsQL queries causing memory spikes
- Grafana datasource configuration fails: Use 'http://victoriametrics:8428' as URL and select 'Prometheus' as datasource type, not VictoriaMetrics
- Missing metrics data in Grafana dashboards: Verify metrics are being ingested via VictoriaMetrics API at http://localhost:8428/api/v1/query
- VictoriaMetrics API returns 'out of disk space' errors: Monitor available storage and adjust retention period using --retentionPeriod parameter

