Quick start #

How to install #

VictoriaMetrics is available in the following distributions:

• Single-server-VictoriaMetrics - all-in-one binary that is easy to run and maintain. Single-server-VictoriaMetrics perfectly scales vertically and easily handles millions of metrics;
• VictoriaMetrics Cluster - set of components for building horizontally scalable clusters.
• VictoriaMetrics Cloud -
  VictoriaMetrics installation in the cloud. Users can pick a suitable installation size and don’t think of typical DevOps tasks such as configuration tuning, monitoring, logs collection, access protection, software updates, backups, etc.

VictoriaMetrics is available as:

• docker images at Docker Hub and Quay
• Helm Charts
• Binary releases
• Ansible Roles
• Source code. See How to build from sources
• VictoriaMetrics on Linode
• VictoriaMetrics on DigitalOcean

Just download VictoriaMetrics and follow these instructions. Then read Prometheus setup and Grafana setup docs.

VictoriaMetrics is developed at a fast pace, so it is recommended periodically checking the CHANGELOG and performing regular upgrades.

Starting VictoriaMetrics Single Node or Cluster on VictoriaMetrics Cloud #

The following steps will guide you through starting VictoriaMetrics on VictoriaMetrics Cloud:

1. Go to VictoriaMetrics Cloud and sign up (it’s free).
2. After signing up, you will be immediately granted $200 of trial credits you can spend on running Single node or Cluster.
3. Navigate to the VictoriaMetrics Cloud quick start guide for detailed instructions.

Starting VictoriaMetrics Single Node via Docker #

Download the latest available Docker image of VictoriaMetrics and start it at port 8428, while storing the ingested data at victoria-metrics-data subdirectory under the current directory:

docker pull victoriametrics/victoria-metrics:v1.114.0
docker run -it --rm -v `pwd`/victoria-metrics-data:/victoria-metrics-data -p 8428:8428 \
 victoriametrics/victoria-metrics:v1.114.0 --selfScrapeInterval=5s -storageDataPath=victoria-metrics-data

You should see:

 started server at http://0.0.0.0:8428/
 partition "2025_03" has been created

Open http://localhost:8428/vmui in WEB browser to see graphical interface vmui. With --selfScrapeInterval=5s VictoriaMetrics scrapes its own metrics, and they should become queryable 30s after start. Visit http://localhost:8428/vmui/#/metrics to explore available metrics or run an arbitrary query at http://localhost:8428/vmui (i.e. process_cpu_cores_available). Other available HTTP endpoints are listed on http://localhost:8428 page.

See more about writing or reading.

Starting VictoriaMetrics Cluster via Docker #

Clone VictoriaMetrics repository and start the docker environment via make docker-cluster-up command:

git clone https://github.com/VictoriaMetrics/VictoriaMetrics && cd VictoriaMetrics
make docker-cluster-up

You should see:

 ✔ Container vmstorage-1        Started                                                                                                                                                0.4s
 ✔ Container vmselect-1         Started                                                                                                                                                0.4s
 ✔ Container vminsert           Started                                                                                                                                                0.4s
 ✔ Container vmagent            Started

The command starts a set of VictoriaMetrics components for metrics collection, storing, alerting and Grafana for user interface. See the full description here.

Visit Grafana http://localhost:3000/ (admin:admin) or vmui http://localhost:8427/select/0/vmui to start exploring metrics.

Further customization is possible by editing the docker-compose-cluster.yml file.

See more details about cluster architecture.

Starting VictoriaMetrics Single Node from a Binary #

1. Download the correct binary for your OS and architecture from GitHub. For Enterprise binaries see this link.

2. Extract the archive to /usr/local/bin by running:

sudo tar -xvf <victoriametrics-archive> -C /usr/local/bin

Replace <victoriametrics-archive> with the path to the archive you downloaded in step 1.

3. Create a VictoriaMetrics user on the system:

sudo useradd -s /usr/sbin/nologin victoriametrics

4. Create a folder for storing VictoriaMetrics data:

sudo mkdir -p /var/lib/victoria-metrics && sudo chown -R victoriametrics:victoriametrics /var/lib/victoria-metrics

5. Create a Linux Service by running the following:

sudo bash -c 'cat <<END >/etc/systemd/system/victoriametrics.service
[Unit]
Description=VictoriaMetrics service
After=network.target

[Service]
Type=simple
User=victoriametrics
Group=victoriametrics
ExecStart=/usr/local/bin/victoria-metrics-prod -storageDataPath=/var/lib/victoria-metrics -retentionPeriod=90d -selfScrapeInterval=10s
SyslogIdentifier=victoriametrics
Restart=always

PrivateTmp=yes
ProtectHome=yes
NoNewPrivileges=yes

ProtectSystem=full

[Install]
WantedBy=multi-user.target
END'

Extra command-line flags can be added to ExecStart line.

If you want to deploy VictoriaMetrics Single Node as a Windows Service review the running as a Windows service docs.

Please note, victoriametrics service is listening on :8428 for HTTP connections (see -httpListenAddr flag).

6. Start and enable the service by running the following command:

sudo systemctl daemon-reload && sudo systemctl enable --now victoriametrics.service

7. Check that service started successfully:

sudo systemctl status victoriametrics.service

8. After VictoriaMetrics is in Running state, verify vmui is working by going to http://<ip_or_hostname>:8428/vmui.

Starting VictoriaMetrics Cluster from Binaries #

VictoriaMetrics cluster consists of 3 components. It is recommended to run these components in the same private network (for security reasons), but on the separate physical nodes for the best performance.

On all nodes you will need to do the following:

1. Download the correct binary for your OS and architecture with -cluster suffix from GitHub. For Enterprise binaries see this link.

2. Extract the archive to /usr/local/bin by running:

sudo tar -xvf <victoriametrics-archive> -C /usr/local/bin

Replace <victoriametrics-archive> with the path to the archive you downloaded in step 1

3. Create a user account for VictoriaMetrics:

sudo useradd -s /usr/sbin/nologin victoriametrics

See recommendations for installing each type of cluster component below.

Installing vmstorage #

1. Create a folder for storing vmstorage data:

sudo mkdir -p /var/lib/vmstorage && sudo chown -R victoriametrics:victoriametrics /var/lib/vmstorage

2. Create a Linux Service for vmstorage service by running the following command:

sudo bash -c 'cat <<END >/etc/systemd/system/vmstorage.service
[Unit]
Description=VictoriaMetrics vmstorage service
After=network.target

[Service]
Type=simple
User=victoriametrics
Group=victoriametrics
Restart=always
ExecStart=/usr/local/bin/vmstorage-prod -retentionPeriod=90d -storageDataPath=/var/lib/vmstorage

PrivateTmp=yes
NoNewPrivileges=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target
END'

Extra command-line flags for vmstorage can be added to ExecStart line.

Please note, vmstorage service is listening on :8400 for vminsert connections (see -vminsertAddr flag), on :8401 for vmselect connections (see --vmselectAddr flag) and on :8482 for HTTP connections (see -httpListenAddr flag).

3. Start and Enable vmstorage:

sudo systemctl daemon-reload && sudo systemctl enable --now vmstorage

4. Check that service started successfully:

sudo systemctl status vmstorage

5. After vmstorage is in Running state, confirm the service is healthy by visiting http://<ip_or_hostname>:8482/-/healthy link. It should say “VictoriaMetrics is Healthy”.

Installing vminsert #

1. Create a Linux Service for vminsert by running the following command:

sudo bash -c 'cat <<END >/etc/systemd/system/vminsert.service
[Unit]
Description=VictoriaMetrics vminsert service
After=network.target

[Service]
Type=simple
User=victoriametrics
Group=victoriametrics
Restart=always
ExecStart=/usr/local/bin/vminsert-prod -storageNode=<list of vmstorages>

PrivateTmp=yes
NoNewPrivileges=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target
END'

Replace <list of vmstorages> with addresses of previously configured vmstorage services. To specify multiple addresses you can repeat the flag multiple times, or separate addresses with commas in one flag. See more details in -storageNode flag description here.

Please note, vminsert service is listening on :8480 for HTTP connections (see -httpListenAddr flag).

2. Start and Enable vminsert:

sudo systemctl daemon-reload && sudo systemctl enable --now vminsert.service

3. Check that service started successfully:

sudo systemctl status vminsert.service

4. After vminsert is in Running state, confirm the service is healthy by visiting http://<ip_or_hostname>:8480/-/healthy link. It should say “VictoriaMetrics is Healthy”

Installing vmselect #

1. Create a folder to store temporary cache:

sudo mkdir -p /var/lib/vmselect-cache && sudo chown -R victoriametrics:victoriametrics /var/lib/vmselect-cache

2. Add a Linux Service for vmselect by running

sudo bash -c 'cat <<END >/etc/systemd/system/vmselect.service
[Unit]
Description=VictoriaMetrics vmselect service
After=network.target

[Service]
Type=simple
User=victoriametrics
Group=victoriametrics
Restart=always
ExecStart=/usr/local/bin/vmselect-prod -storageNode=<list of vmstorages> -cacheDataPath=/var/lib/vmselect-cache

PrivateTmp=yes
NoNewPrivileges=yes

ProtectSystem=full

[Install]
WantedBy=multi-user.target
END'

Replace <list of vmstorages> with addresses of previously configured vmstorage services. To specify multiple addresses you can repeat the flag multiple times, or separate addresses with commas in one flag. See more details in -storageNode flag description here.

Please note, vmselect service is listening on :8481 for HTTP connections (see -httpListenAddr flag).

3. Start and Enable vmselect:

sudo systemctl daemon-reload && sudo systemctl enable --now vmselect.service

4. Make sure the vmselect service is running:

sudo systemctl status vmselect.service

5. After vmselect is in Running state, confirm the service is healthy by visiting http://<ip_or_hostname>:8481/select/0/vmui link. It should open vmui page.

Write data #

There are two main models in monitoring for data collection: push and pull. Both are used in modern monitoring and both are supported by VictoriaMetrics.

See more details on writing data here. See documentation for configuring metrics collectors.

Query data #

VictoriaMetrics has built-in vmui - graphical User Interface for querying and visualizing metrics. MetricsQL - is the query language for executing read queries in VictoriaMetrics. See examples of MetricsQL queries here.

VictoriaMetrics provides an HTTP API for serving read queries. The API is used in various integrations such as Grafana.

See more details on querying data here.

Alerting #

To run periodic conditions checks use vmalert. It allows creating set of conditions using MetricsQL expressions and send notifications to Alertmanager when such conditions are met.

See vmalert quick start.

Data migration #

Migrating data from other TSDBs to VictoriaMetrics is as simple as importing data via any of supported formats.

The migration might get easier when using vmctl - VictoriaMetrics command line tool. It supports the following databases for migration to VictoriaMetrics:

• Prometheus using snapshot API;
• Thanos;
• InfluxDB;
• OpenTSDB;
• Migrate data between VictoriaMetrics single and cluster versions.

Productionization #

When going to production with VictoriaMetrics we recommend following the recommendations.

Monitoring #

Each VictoriaMetrics component emits its own metrics with various details regarding performance and health state. Docs for the components also contain a Monitoring section with an explanation of what and how should be monitored. For example, Single-server-VictoriaMetrics Monitoring.

VictoriaMetrics has a list of Grafana dashboards. Each dashboard contains a lot of useful information and tips. It is recommended to have these dashboards installed and up to date.

Using the recommended alerting rules will help to identify unwanted issues.

The rule of thumb is to have a separate installation of VictoriaMetrics or any other monitoring system to monitor the production installation of VictoriaMetrics. This would make monitoring independent and will help identify problems with the main monitoring installation.

See more details in the article VictoriaMetrics Monitoring.

Capacity planning #

See capacity planning sections in docs for Single-server-VictoriaMetrics and VictoriaMetrics Cluster.

Capacity planning isn’t possible without monitoring, so consider configuring it first. Understanding resource usage and performance of VictoriaMetrics also requires knowing the tech terms active series, churn rate, cardinality, slow inserts. All of them are present in Grafana dashboards.

Data safety #

It is recommended to read Replication and data safety, Why replication doesn’t save from disaster? and backups.

Configuring limits #

To avoid excessive resource usage or performance degradation limits must be in place:

• Resource usage limits;
• Cardinality limiter.

Security recommendations #

• Security recommendations for single-node VictoriaMetrics
• Security recommendations for cluster version of VictoriaMetrics