From 3ad36134f6ef1e1f9e7f05662a4d5a60b1e70950 Mon Sep 17 00:00:00 2001 From: Edouard Hur <3418467+hekmon@users.noreply.github.com> Date: Wed, 26 Feb 2020 12:21:19 +0100 Subject: [PATCH] Readme markdown linting (#338) * fixed MD009/no-trailing-spaces * fixed MD033/no-inline-html: Inline HTML * fixed MD012/no-multiple-blanks * fixed MD007/ul-indent * fixed MD004/ul-style * fixed MD031/blanks-around-fences * fixed MD040/fenced-code-language * fixed MD032/blanks-around-lists * fixed MD026/no-trailing-punctuation --- README.md | 321 +++++++++++++++++++++++------------------------------- 1 file changed, 137 insertions(+), 184 deletions(-) diff --git a/README.md b/README.md index 4b8410322..86d48e15a 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Build Status](https://github.com/VictoriaMetrics/VictoriaMetrics/workflows/main/badge.svg)](https://github.com/VictoriaMetrics/VictoriaMetrics/actions) [![codecov](https://codecov.io/gh/VictoriaMetrics/VictoriaMetrics/branch/master/graph/badge.svg)](https://codecov.io/gh/VictoriaMetrics/VictoriaMetrics) -Victoria Metrics +![Victoria Metrics logo](logo.png "Victoria Metrics") ## VictoriaMetrics @@ -17,7 +17,6 @@ in [source code](https://github.com/VictoriaMetrics/VictoriaMetrics). Just downl Cluster version is available [here](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/cluster). - ## Case studies and talks * [Adidas](https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/CaseStudies#adidas) @@ -26,7 +25,6 @@ Cluster version is available [here](https://github.com/VictoriaMetrics/VictoriaM * [Wedos.com](https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/CaseStudies#wedoscom) * [Dreamteam](https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/CaseStudies#dreamteam) - ## Prominent features * Supports [Prometheus querying API](https://prometheus.io/docs/prometheus/latest/querying/api/), so it can be used as Prometheus drop-in replacement in Grafana. @@ -66,64 +64,61 @@ Cluster version is available [here](https://github.com/VictoriaMetrics/VictoriaM * Ideally works with big amounts of time series data from Kubernetes, IoT sensors, connected cars, industrial telemetry, financial data and various Enterprise workloads. * Has open source [cluster version](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/cluster). - ## Operation - ### Table of contents - - [How to start VictoriaMetrics](#how-to-start-victoriametrics) - - [Environment variables](#environment-variables) - - [Prometheus setup](#prometheus-setup) - - [Grafana setup](#grafana-setup) - - [How to upgrade VictoriaMetrics?](#how-to-upgrade-victoriametrics) - - [How to apply new config to VictoriaMetrics?](#how-to-apply-new-config-to-victoriametrics) - - [How to scrape Prometheus exporters such as node_exporter?](#how-to-scrape-prometheus-exporters-such-as-node-exporter) - - [How to send data from InfluxDB-compatible agents such as Telegraf?](#how-to-send-data-from-influxdb-compatible-agents-such-as-telegraf) - - [How to send data from Graphite-compatible agents such as StatsD?](#how-to-send-data-from-graphite-compatible-agents-such-as-statsd) - - [Querying Graphite data](#querying-graphite-data) - - [How to send data from OpenTSDB-compatible agents?](#how-to-send-data-from-opentsdb-compatible-agents) - - [Prometheus querying API usage](#prometheus-querying-api-usage) - - [How to build from sources](#how-to-build-from-sources) - - [Development build](#development-build) - - [Production build](#production-build) - - [ARM build](#arm-build) - - [Pure Go build (CGO_ENABLED=0)](#pure-go-build-cgo_enabled0) - - [Building docker images](#building-docker-images) - - [Start with docker-compose](#start-with-docker-compose) - - [Setting up service](#setting-up-service) - - [How to work with snapshots?](#how-to-work-with-snapshots) - - [How to delete time series?](#how-to-delete-time-series) - - [How to export time series?](#how-to-export-time-series) - - [How to import time series data?](#how-to-import-time-series-data) - - [Federation](#federation) - - [Capacity planning](#capacity-planning) - - [High availability](#high-availability) - - [Deduplication](#deduplication) - - [Retention](#retention) - - [Multiple retentions](#multiple-retentions) - - [Downsampling](#downsampling) - - [Multi-tenancy](#multi-tenancy) - - [Scalability and cluster version](#scalability-and-cluster-version) - - [Alerting](#alerting) - - [Security](#security) - - [Tuning](#tuning) - - [Monitoring](#monitoring) - - [Troubleshooting](#troubleshooting) - - [Backfilling](#backfilling) - - [Profiling](#profiling) -- [Integrations](#integrations) -- [Roadmap](#roadmap) -- [Contacts](#contacts) -- [Community and contributions](#community-and-contributions) -- [Third-party contributions](#third-party-contributions) -- [Reporting bugs](#reporting-bugs) -- [Victoria Metrics Logo](#victoria-metrics-logo) - - [Logo Usage Guidelines](#logo-usage-guidelines) - - [Font used:](#font-used) - - [Color Palette:](#color-palette) - - [We kindly ask:](#we-kindly-ask) - +* [How to start VictoriaMetrics](#how-to-start-victoriametrics) + * [Environment variables](#environment-variables) +* [Prometheus setup](#prometheus-setup) +* [Grafana setup](#grafana-setup) +* [How to upgrade VictoriaMetrics](#how-to-upgrade-victoriametrics) +* [How to apply new config to VictoriaMetrics](#how-to-apply-new-config-to-victoriametrics) +* [How to scrape Prometheus exporters such as node_exporter](#how-to-scrape-prometheus-exporters-such-as-node-exporter) +* [How to send data from InfluxDB-compatible agents such as Telegraf](#how-to-send-data-from-influxdb-compatible-agents-such-as-telegraf) +* [How to send data from Graphite-compatible agents such as StatsD](#how-to-send-data-from-graphite-compatible-agents-such-as-statsd) +* [Querying Graphite data](#querying-graphite-data) +* [How to send data from OpenTSDB-compatible agents](#how-to-send-data-from-opentsdb-compatible-agents) +* [Prometheus querying API usage](#prometheus-querying-api-usage) +* [How to build from sources](#how-to-build-from-sources) + * [Development build](#development-build) + * [Production build](#production-build) + * [ARM build](#arm-build) + * [Pure Go build (CGO_ENABLED=0)](#pure-go-build-cgo_enabled0) + * [Building docker images](#building-docker-images) +* [Start with docker-compose](#start-with-docker-compose) +* [Setting up service](#setting-up-service) +* [How to work with snapshots](#how-to-work-with-snapshots) +* [How to delete time series](#how-to-delete-time-series) +* [How to export time series](#how-to-export-time-series) +* [How to import time series data](#how-to-import-time-series-data) +* [Federation](#federation) +* [Capacity planning](#capacity-planning) +* [High availability](#high-availability) +* [Deduplication](#deduplication) +* [Retention](#retention) +* [Multiple retentions](#multiple-retentions) +* [Downsampling](#downsampling) +* [Multi-tenancy](#multi-tenancy) +* [Scalability and cluster version](#scalability-and-cluster-version) +* [Alerting](#alerting) +* [Security](#security) +* [Tuning](#tuning) +* [Monitoring](#monitoring) +* [Troubleshooting](#troubleshooting) +* [Backfilling](#backfilling) +* [Profiling](#profiling) +* [Integrations](#integrations) +* [Roadmap](#roadmap) +* [Contacts](#contacts) +* [Community and contributions](#community-and-contributions) +* [Third-party contributions](#third-party-contributions) +* [Reporting bugs](#reporting-bugs) +* [Victoria Metrics Logo](#victoria-metrics-logo) + * [Logo Usage Guidelines](#logo-usage-guidelines) + * [Font used](#font-used) + * [Color Palette](#color-palette) + * [We kindly ask](#we-kindly-ask) ### How to start VictoriaMetrics @@ -150,8 +145,8 @@ Each flag values can be set thru environment variables by following these rules: ### Prometheus setup -Prometheus must be configured with [remote_write](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) -in order to send data to VictoriaMetrics. Add the following lines +Prometheus must be configured with [remote_write](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) +in order to send data to VictoriaMetrics. Add the following lines to Prometheus config file (it is usually located at `/etc/prometheus/prometheus.yml`): ```yml @@ -162,7 +157,7 @@ remote_write: Substitute `` with the hostname or IP address of VictoriaMetrics. Then apply the new config via the following command: -``` +```bash kill -HUP `pidof prometheus` ``` @@ -185,7 +180,8 @@ across Prometheus instances, so those time series may be filtered and grouped by For highly loaded Prometheus instances (400k+ samples per second) the following tuning may be applied: -``` + +```yaml remote_write: - url: http://:8428/api/v1/write queue_config: @@ -196,19 +192,18 @@ remote_write: Using remote write increases memory usage for Prometheus up to ~25% and depends on the shape of data. If you are experiencing issues with -too high memory consumption try to lower `max_samples_per_send` +too high memory consumption try to lower `max_samples_per_send` and `capacity` params (keep in mind that these two params are tightly connected). Read more about tuning remote write for Prometheus [here](https://prometheus.io/docs/practices/remote_write). It is recommended upgrading Prometheus to [v2.12.0](https://github.com/prometheus/prometheus/releases) or newer, since the previous versions may have issues with `remote_write`. - ### Grafana setup Create [Prometheus datasource](http://docs.grafana.org/features/datasources/prometheus/) in Grafana with the following Url: -``` +```url http://:8428 ``` @@ -217,8 +212,7 @@ Substitute `` with the hostname or IP address of VictoriaM Then build graphs with the created datasource using [Prometheus query language](https://prometheus.io/docs/prometheus/latest/querying/basics/). VictoriaMetrics supports native PromQL and [extends it with useful features](https://github.com/VictoriaMetrics/VictoriaMetrics/wiki/MetricsQL). - -### How to upgrade VictoriaMetrics? +### How to upgrade VictoriaMetrics It is safe upgrading VictoriaMetrics to new versions unless [release notes](https://github.com/VictoriaMetrics/VictoriaMetrics/releases) say otherwise. It is recommended performing regular upgrades to the latest version, @@ -233,8 +227,7 @@ Follow the following steps during the upgrade: Prometheus doesn't drop data during VictoriaMetrics restart. See [this article](https://grafana.com/blog/2019/03/25/whats-new-in-prometheus-2.8-wal-based-remote-write/) for details. - -### How to apply new config to VictoriaMetrics? +### How to apply new config to VictoriaMetrics VictoriaMetrics must be restarted for applying new config: @@ -245,8 +238,7 @@ VictoriaMetrics must be restarted for applying new config: Prometheus doesn't drop data during VictoriaMetrics restart. See [this article](https://grafana.com/blog/2019/03/25/whats-new-in-prometheus-2.8-wal-based-remote-write/) for details. - -### How to scrape Prometheus exporters such as [node-exporter](https://github.com/prometheus/node_exporter)? +### How to scrape Prometheus exporters such as [node-exporter](https://github.com/prometheus/node_exporter) VictoriaMetrics can be used as drop-in replacement for Prometheus for scraping targets configured in `prometheus.yml` config file according to [the specification](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration-file). Just set `-promscrape.config` command-line flag to the path to `prometheus.yml` config - and VictoriaMetrics should start scraping the configured targets. @@ -259,13 +251,12 @@ In the future other `*_sd_config` types will be supported. See also [vmagent](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/app/vmagent/README.md), which can be used as drop-in replacement for Prometheus. - -### How to send data from InfluxDB-compatible agents such as [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/)? +### How to send data from InfluxDB-compatible agents such as [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) Just use `http://:8428` url instead of InfluxDB url in agents' configs. For instance, put the following lines into `Telegraf` config, so it sends data to VictoriaMetrics instead of InfluxDB: -``` +```toml [[outputs.influxdb]] urls = ["http://:8428"] ``` @@ -275,6 +266,7 @@ Do not forget substituting `` with the real address where Another option is to enable TCP and UDP receiver for Influx line protocol via `-influxListenAddr` command-line flag. VictoriaMetrics maps Influx data using the following rules: + * [`db` query arg](https://docs.influxdata.com/influxdb/v1.7/tools/api/#write-http-endpoint) is mapped into `db` label value unless `db` tag exists in the Influx line. * Field names are mapped to time series names prefixed with `{measurement}{separator}` value, @@ -285,13 +277,13 @@ VictoriaMetrics maps Influx data using the following rules: For example, the following Influx line: -``` +```raw foo,tag1=value1,tag2=value2 field1=12,field2=40 ``` is converted into the following Prometheus data points: -``` +```raw foo_field1{tag1="value1", tag2="value2"} 12 foo_field2{tag1="value1", tag2="value2"} 40 ``` @@ -299,20 +291,20 @@ foo_field2{tag1="value1", tag2="value2"} 40 Example for writing data with [Influx line protocol](https://docs.influxdata.com/influxdb/v1.7/write_protocols/line_protocol_tutorial/) to local VictoriaMetrics using `curl`: -``` +```bash curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST 'http://localhost:8428/write' ``` An arbitrary number of lines delimited by '\n' may be sent in a single request. After that the data may be read via [/api/v1/export](#how-to-export-time-series) endpoint: -``` +```bash curl -G 'http://localhost:8428/api/v1/export' -d 'match={__name__=~"measurement_.*"}' ``` The `/api/v1/export` endpoint should return the following response: -``` +```jsonl {"metric":{"__name__":"measurement_field1","tag1":"value1","tag2":"value2"},"values":[123],"timestamps":[1560272508147]} {"metric":{"__name__":"measurement_field2","tag1":"value1","tag2":"value2"},"values":[1.23],"timestamps":[1560272508147]} ``` @@ -320,23 +312,21 @@ The `/api/v1/export` endpoint should return the following response: Note that Influx line protocol expects [timestamps in *nanoseconds* by default](https://docs.influxdata.com/influxdb/v1.7/write_protocols/line_protocol_tutorial/#timestamp), while VictoriaMetrics stores them with *milliseconds* precision. - -### How to send data from Graphite-compatible agents such as [StatsD](https://github.com/etsy/statsd)? +### How to send data from Graphite-compatible agents such as [StatsD](https://github.com/etsy/statsd) 1) Enable Graphite receiver in VictoriaMetrics by setting `-graphiteListenAddr` command line flag. For instance, the following command will enable Graphite receiver in VictoriaMetrics on TCP and UDP port `2003`: -``` +```bash /path/to/victoria-metrics-prod -graphiteListenAddr=:2003 ``` 2) Use the configured address in Graphite-compatible agents. For instance, set `graphiteHost` to the VictoriaMetrics host in `StatsD` configs. - Example for writing data with Graphite plaintext protocol to local VictoriaMetrics using `nc`: -``` +```bash echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" | nc -N localhost 2003 ``` @@ -344,26 +334,23 @@ VictoriaMetrics sets the current time if the timestamp is omitted. An arbitrary number of lines delimited by `\n` may be sent in one go. After that the data may be read via [/api/v1/export](#how-to-export-time-series) endpoint: -``` +```bash curl -G 'http://localhost:8428/api/v1/export' -d 'match=foo.bar.baz' ``` The `/api/v1/export` endpoint should return the following response: -``` +```bash {"metric":{"__name__":"foo.bar.baz","tag1":"value1","tag2":"value2"},"values":[123],"timestamps":[1560277406000]} ``` - ### Querying Graphite data Data sent to VictoriaMetrics via `Graphite plaintext protocol` may be read either via [Prometheus querying API](#prometheus-querying-api-usage) or via [go-graphite/carbonapi](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.prometheus.yaml). - - -### How to send data from OpenTSDB-compatible agents? +### How to send data from OpenTSDB-compatible agents VictoriaMetrics supports [telnet put protocol](http://opentsdb.net/docs/build/html/api_telnet/put.html) and [HTTP /api/put requests](http://opentsdb.net/docs/build/html/api_http/put.html) for ingesting OpenTSDB data. @@ -373,39 +360,37 @@ and [HTTP /api/put requests](http://opentsdb.net/docs/build/html/api_http/put.ht 1) Enable OpenTSDB receiver in VictoriaMetrics by setting `-opentsdbListenAddr` command line flag. For instance, the following command enables OpenTSDB receiver in VictoriaMetrics on TCP and UDP port `4242`: -``` +```bash /path/to/victoria-metrics-prod -opentsdbListenAddr=:4242 ``` 2) Send data to the given address from OpenTSDB-compatible agents. - Example for writing data with OpenTSDB protocol to local VictoriaMetrics using `nc`: -``` +```bash echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2" | nc -N localhost 4242 ``` An arbitrary number of lines delimited by `\n` may be sent in one go. After that the data may be read via [/api/v1/export](#how-to-export-time-series) endpoint: -``` +```bash curl -G 'http://localhost:8428/api/v1/export' -d 'match=foo.bar.baz' ``` The `/api/v1/export` endpoint should return the following response: -``` +```bash {"metric":{"__name__":"foo.bar.baz","tag1":"value1","tag2":"value2"},"values":[123],"timestamps":[1560277292000]} ``` - #### Sending OpenTSDB data via HTTP `/api/put` requests 1) Enable HTTP server for OpenTSDB `/api/put` requests by setting `-opentsdbHTTPListenAddr` command line flag. For instance, the following command enables OpenTSDB HTTP server on port `4242`: -``` +```bash /path/to/victoria-metrics-prod -opentsdbHTTPListenAddr=:4242 ``` @@ -413,31 +398,30 @@ the following command enables OpenTSDB HTTP server on port `4242`: Example for writing a single data point: -``` +```bash curl -H 'Content-Type: application/json' -d '{"metric":"x.y.z","value":45.34,"tags":{"t1":"v1","t2":"v2"}}' http://localhost:4242/api/put ``` Example for writing multiple data points in a single request: -``` +```bash curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://localhost:4242/api/put ``` After that the data may be read via [/api/v1/export](#how-to-export-time-series) endpoint: -``` +```bash curl -G 'http://localhost:8428/api/v1/export' -d 'match[]=x.y.z' -d 'match[]=foo' -d 'match[]=bar' ``` The `/api/v1/export` endpoint should return the following response: -``` +```bash {"metric":{"__name__":"foo"},"values":[45.34],"timestamps":[1566464846000]} {"metric":{"__name__":"bar"},"values":[43],"timestamps":[1566464846000]} {"metric":{"__name__":"x.y.z","t1":"v1","t2":"v2"},"values":[45.34],"timestamps":[1566464763000]} ``` - ### Prometheus querying API usage VictoriaMetrics supports the following handlers from [Prometheus querying API](https://prometheus.io/docs/prometheus/latest/querying/api/): @@ -462,7 +446,6 @@ Additionally VictoriaMetrics provides the following handlers: so it can be slow if the database contains tens of millions of time series. * `/api/v1/labels/count` - it returns a list of `label: values_count` entries. It can be used for determining labels with the maximum number of values. - ### How to build from sources We recommend using either [binary releases](https://github.com/VictoriaMetrics/VictoriaMetrics/releases) or @@ -470,7 +453,6 @@ We recommend using either [binary releases](https://github.com/VictoriaMetrics/V from sources. Building from sources is reasonable when developing additional features specific to your needs. - #### Development build 1. [Install Go](https://golang.org/doc/install). The minimum supported version is Go 1.12. @@ -515,27 +497,24 @@ Run `make package-victoria-metrics`. It builds `victoriametrics/victoria-metrics `` is auto-generated image tag, which depends on source code in the repository. The `` may be manually set via `PKG_TAG=foobar make package-victoria-metrics`. - ### Start with docker-compose [Docker-compose](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/deployment/docker/docker-compose.yml) helps to spin up VictoriaMetrics, Prometheus and Grafana with one command. More details may be found [here](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/deployment/docker#folder-contains-basic-images-and-tools-for-building-and-running-victoria-metrics-in-docker). - ### Setting up service Read [these instructions](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/43) on how to set up VictoriaMetrics as a service in your OS. - -### How to work with snapshots? +### How to work with snapshots VictoriaMetrics can create [instant snapshots](https://medium.com/@valyala/how-victoriametrics-makes-instant-snapshots-for-multi-terabyte-time-series-data-e1f3fb0e0282) for all the data stored under `-storageDataPath` directory. Navigate to `http://:8428/snapshot/create` in order to create an instant snapshot. The page will return the following JSON response: -``` +```json {"status":"ok","snapshot":""} ``` @@ -551,13 +530,13 @@ to delete `` snapshot. Navigate to `http://:8428/snapshot/delete_all` in order to delete all the snapshots. Steps for restoring from a snapshot: + 1. Stop VictoriaMetrics with `kill -INT`. 2. Restore snapshot contents from backup with [vmrestore](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/app/vmrestore/README.md) to the directory pointed by `-storageDataPath`. 3. Start VictoriaMetrics. - -### How to delete time series? +### How to delete time series Send a request to `http://:8428/api/v1/admin/tsdb/delete_series?match[]=`, where `` may contain any [time series selector](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-series-selectors) @@ -569,20 +548,19 @@ before actually deleting the metrics. The delete API is intended mainly for the following cases: -- One-off deleting of accidentally written invalid (or undesired) time series. -- One-off deleting of user data due to [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation). +* One-off deleting of accidentally written invalid (or undesired) time series. +* One-off deleting of user data due to [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation). It isn't recommended using delete API for the following cases, since it brings non-zero overhead: -- Regular cleanups for unneded data. Just prevent writing unneeded data into VictoriaMetrics. +* Regular cleanups for unneded data. Just prevent writing unneeded data into VictoriaMetrics. See [this article](https://www.robustperception.io/relabelling-can-discard-targets-timeseries-and-alerts) for details. -- Reducing disk space usage by deleting unneded time series. This doesn't work as expected, since the deleted +* Reducing disk space usage by deleting unneded time series. This doesn't work as expected, since the deleted time series occupy disk space until the next merge operation, which can never occur. It is better using `-retentionPeriod` command-line flag for efficient pruning of old data. - -### How to export time series? +### How to export time series Send a request to `http://:8428/api/v1/export?match[]=`, where `` may contain any [time series selector](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-series-selectors) @@ -590,7 +568,7 @@ for metrics to export. Use `{__name__!=""}` selector for fetching all the time s The response would contain all the data for the selected time series in [JSON streaming format](https://en.wikipedia.org/wiki/JSON_streaming#Line-delimited_JSON). Each JSON line would contain data for a single time series. An example output: -``` +```jsonl {"metric":{"__name__":"up","job":"node_exporter","instance":"localhost:9100"},"values":[0,0,0],"timestamps":[1549891472010,1549891487724,1549891503438]} {"metric":{"__name__":"up","job":"prometheus","instance":"localhost:9090"},"values":[1,1,1],"timestamps":[1549891461511,1549891476511,1549891491511]} ``` @@ -601,7 +579,7 @@ unix timestamp in seconds or [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) val Pass `Accept-Encoding: gzip` HTTP header in the request to `/api/v1/export` in order to reduce network bandwidth during exporing big amounts of time series data. This enables gzip compression for the exported data. Example for exporting gzipped data: -``` +```bash curl -H 'Accept-Encoding: gzip' http://localhost:8428/api/v1/export -d 'match[]={__name__!=""}' > data.jsonl.gz ``` @@ -609,8 +587,7 @@ The maximum duration for each request to `/api/v1/export` is limited by `-search Exported data can be imported via POST'ing it to [/api/v1/import](#how-to-import-time-series-data). - -### How to import time series data? +### How to import time series data Time series data can be imported via any supported ingestion protocol: @@ -623,7 +600,7 @@ Time series data can be imported via any supported ingestion protocol: The most efficient protocol for importing data into VictoriaMetrics is `/api/v1/import`. Example for importing data obtained via `/api/v1/export`: -``` +```bash # Export the data from : curl http://source-victoriametrics:8428/api/v1/export -d 'match={__name__!=""}' > exported_data.jsonl @@ -633,7 +610,7 @@ curl -X POST http://destination-victoriametrics:8428/api/v1/import -T exported_d Pass `Content-Encoding: gzip` HTTP request header to `/api/v1/import` for importing gzipped data: -``` +```bash # Export gzipped data from : curl -H 'Accept-Encoding: gzip' http://source-victoriametrics:8428/api/v1/export -d 'match={__name__!=""}' > exported_data.jsonl.gz @@ -644,7 +621,6 @@ curl -X POST -H 'Content-Encoding: gzip' http://destination-victoriametrics:8428 Each request to `/api/v1/import` can load up to a single vCPU core on VictoriaMetrics. Import speed can be improved by splitting the original file into smaller parts and importing them concurrently. Note that the original file must be split on newlines. - ### Federation VictoriaMetrics exports [Prometheus-compatible federation data](https://prometheus.io/docs/prometheus/latest/federation/) @@ -656,7 +632,6 @@ on the interval `[now - max_lookback ... now]` is scraped for each time series. For instance, `/federate?match[]=up&max_lookback=1h` would return last points on the `[now - 1h ... now]` interval. This may be useful for time series federation with scrape intervals exceeding `5m`. - ### Capacity planning A rough estimation of the required resources for ingestion path: @@ -684,7 +659,6 @@ A rough estimation of the required resources for ingestion path: The actual ingress bandwidth usage depends on the average number of labels per ingested metric and the average size of label values. The higher number of per-metric labels and longer label values mean the higher ingress bandwidth. - The required resources for query path: * RAM size: depends on the number of time series to scan in each query and the `step` @@ -696,7 +670,6 @@ The required resources for query path: * Network usage: depends on the frequency and the type of incoming requests. Typical Grafana dashboards usually require negligible network bandwidth. - ### High availability 1) Install multiple VictoriaMetrics instances in distinct datacenters (availability zones). @@ -715,7 +688,7 @@ remote_write: 3) Apply the updated config: -``` +```bash kill -HUP `pidof prometheus` ``` @@ -723,14 +696,12 @@ kill -HUP `pidof prometheus` 5) Set up [Promxy](https://github.com/jacksontj/promxy) in front of all the VictoriaMetrics replicas. 6) Set up Prometheus datasource in Grafana that points to Promxy. - If you have Prometheus HA pairs with replicas `r1` and `r2` in each pair, then configure each `r1` to write data to `victoriametrics-addr-1`, while each `r2` should write data to `victoriametrics-addr-2`. Another option is to write data simultaneously from Prometheus HA pair to a pair of VictoriaMetrics instances with the enabled de-duplication. See [this section](#deduplication) for details. - ### Deduplication VictoriaMetrics de-duplicates data points if `-dedup.minScrapeInterval` command-line flag @@ -740,7 +711,6 @@ The de-duplication reduces disk space usage if multiple identically configured P write data to the same VictoriaMetrics instance. Note that these Prometheus instances must have identical `external_labels` section in their configs, so they write data to the same time series. - ### Retention Retention is configured with `-retentionPeriod` command-line flag. For instance, `-retentionPeriod=3` means @@ -750,7 +720,6 @@ Directories for months outside the configured retention are deleted on the first In order to keep data according to `-retentionPeriod` max disk space usage is going to be `-retentionPeriod` + 1 month. For example if `-retentionPeriod` is set to 1, data for January is deleted on March 1st. - ### Multiple retentions Just start multiple VictoriaMetrics instances with distinct values for the following flags: @@ -759,24 +728,22 @@ Just start multiple VictoriaMetrics instances with distinct values for the follo * `-storageDataPath`, so the data for each retention period is saved in a separate directory * `-httpListenAddr`, so clients may reach VictoriaMetrics instance with proper retention - ### Downsampling There is no downsampling support at the moment, but: -- VictoriaMetrics is optimized for querying big amounts of raw data. See benchmark results for heavy queries + +* VictoriaMetrics is optimized for querying big amounts of raw data. See benchmark results for heavy queries in [this article](https://medium.com/@valyala/measuring-vertical-scalability-for-time-series-databases-in-google-cloud-92550d78d8ae). -- VictoriaMetrics has good compression for on-disk data. See [this article](https://medium.com/@valyala/victoriametrics-achieving-better-compression-for-time-series-data-than-gorilla-317bc1f95932) +* VictoriaMetrics has good compression for on-disk data. See [this article](https://medium.com/@valyala/victoriametrics-achieving-better-compression-for-time-series-data-than-gorilla-317bc1f95932) for details. These properties reduce the need of downsampling. We plan to implement downsampling in the future. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/36) for details. - ### Multi-tenancy Single-node VictoriaMetrics doesn't support multi-tenancy. Use [cluster version](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/cluster) instead. - ### Scalability and cluster version Though single-node VictoriaMetrics cannot scale to multiple nodes, it is optimized for resource usage - storage size / bandwidth / IOPS, RAM, CPU. @@ -787,15 +754,14 @@ So try single-node VictoriaMetrics at first and then [switch to cluster version] horizontally scalable long-term remote storage for really large Prometheus deployments. [Contact us](mailto:info@victoriametrics.com) for paid support. - ### Alerting VictoriaMetrics doesn't support rule evaluation and alerting yet, so these actions can be performed at the following places: + * At Prometheus - see [the corresponding docs](https://prometheus.io/docs/alerting/overview/). * At Promxy - see [the corresponding docs](https://github.com/jacksontj/promxy/blob/master/README.md#how-do-i-use-alertingrecording-rules-in-promxy). * At Grafana - see [the corresponding docs](https://grafana.com/docs/alerting/rules/). - ### Security Do not forget protecting sensitive endpoints in VictoriaMetrics when exposing it to untrusted networks such as the internet. @@ -810,7 +776,6 @@ Consider setting the following command-line flags: Explicitly set internal network interface for TCP and UDP ports for data ingestion with Graphite and OpenTSDB formats. For example, substitute `-graphiteListenAddr=:2003` with `-graphiteListenAddr=:2003`. - ### Tuning * There is no need for VictoriaMetrics tuning since it uses reasonable defaults for command-line flags, @@ -823,11 +788,10 @@ For example, substitute `-graphiteListenAddr=:2003` with `-graphiteListenAddr=:8428/debug/pprof/heap > mem.pprof ``` -- CPU profile. It can be collected with the following command: -``` +* CPU profile. It can be collected with the following command: + +```bash curl -s http://:8428/debug/pprof/profile > cpu.pprof ``` @@ -908,7 +871,6 @@ The command for collecting CPU profile waits for 30 seconds before returning. The collected profiles may be analyzed with [go tool pprof](https://github.com/google/pprof). - ## Integrations * [netdata](https://github.com/netdata/netdata) can push data into VictoriaMetrics via `Prometheus remote_write API`. @@ -917,65 +879,57 @@ The collected profiles may be analyzed with [go tool pprof](https://github.com/g See [this example](/blob/master/cmd/carbonapi/carbonapi.example.prometheus.yaml). * [Ansible role for installing VictoriaMetrics](https://github.com/dreamteam-gg/ansible-victoriametrics-role). - ## Roadmap -- [ ] Replication [#118](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/118) -- [ ] Support of Object Storages (GCS, S3, Azure Storage) [#38](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/38) -- [ ] Data downsampling [#36](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/36) -- [ ] Alert Manager Integration [#119](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/119) -- [ ] CLI tool for data migration, re-balancing and adding/removing nodes [#103](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/103) - +* [ ] Replication [#118](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/118) +* [ ] Support of Object Storages (GCS, S3, Azure Storage) [#38](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/38) +* [ ] Data downsampling [#36](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/36) +* [ ] Alert Manager Integration [#119](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/119) +* [ ] CLI tool for data migration, re-balancing and adding/removing nodes [#103](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/103) The discussion happens [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/129). Feel free to comment on any item or add you own one. - ## Contacts Contact us with any questions regarding VictoriaMetrics at [info@victoriametrics.com](mailto:info@victoriametrics.com). - ## Community and contributions Feel free asking any questions regarding VictoriaMetrics: -- [slack](http://slack.victoriametrics.com/) -- [reddit](https://www.reddit.com/r/VictoriaMetrics/) -- [telegram-en](https://t.me/VictoriaMetrics_en) -- [telegram-ru](https://t.me/VictoriaMetrics_ru1) -- [google groups](https://groups.google.com/forum/#!forum/victorametrics-users) - +* [slack](http://slack.victoriametrics.com/) +* [reddit](https://www.reddit.com/r/VictoriaMetrics/) +* [telegram-en](https://t.me/VictoriaMetrics_en) +* [telegram-ru](https://t.me/VictoriaMetrics_ru1) +* [google groups](https://groups.google.com/forum/#!forum/victorametrics-users) If you like VictoriaMetrics and want to contribute, then we need the following: -- Filing issues and feature requests [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). -- Spreading a word about VictoriaMetrics: conference talks, articles, comments, experience sharing with colleagues. -- Updating documentation. +* Filing issues and feature requests [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). +* Spreading a word about VictoriaMetrics: conference talks, articles, comments, experience sharing with colleagues. +* Updating documentation. We are open to third-party pull requests provided they follow [KISS design principle](https://en.wikipedia.org/wiki/KISS_principle): -- Prefer simple code and architecture. -- Avoid complex abstractions. -- Avoid magic code and fancy algorithms. -- Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). -- Minimize the number of moving parts in the distributed system. -- Avoid automated decisions, which may hurt cluster availability, consistency or performance. +* Prefer simple code and architecture. +* Avoid complex abstractions. +* Avoid magic code and fancy algorithms. +* Avoid [big external dependencies](https://medium.com/@valyala/stripping-dependency-bloat-in-victoriametrics-docker-image-983fb5912b0d). +* Minimize the number of moving parts in the distributed system. +* Avoid automated decisions, which may hurt cluster availability, consistency or performance. Adhering `KISS` principle simplifies the resulting code and architecture, so it can be reviewed, understood and verified by many people. - ## Third-party contributions * [Unofficial yum repository](https://copr.fedorainfracloud.org/coprs/antonpatsev/VictoriaMetrics/) ([source code](https://github.com/patsevanton/victoriametrics-rpm)) * [Prometheus -> VictoriaMetrics exporter #1](https://github.com/ryotarai/prometheus-tsdb-dump) * [Prometheus -> VictoriaMetrics exporter #2](https://github.com/AnchorFree/tsdb-remote-write) - ## Reporting bugs Report bugs and propose new features [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). - ## Victoria Metrics Logo [Zip](VM_logo.zip) contains three folders with different image orientations (main color and inverted version). @@ -986,22 +940,21 @@ Files included in each folder: * 2 PNG Preview files with transparent background * 2 EPS Adobe Illustrator EPS10 files - ### Logo Usage Guidelines -#### Font used: +#### Font used * Lato Black * Lato Regular -#### Color Palette: +#### Color Palette * HEX [#110f0f](https://www.color-hex.com/color/110f0f) * HEX [#ffffff](https://www.color-hex.com/color/ffffff) -### We kindly ask: +### We kindly ask -- Please don't use any other font instead of suggested. -- There should be sufficient clear space around the logo. -- Do not change spacing, alignment, or relative locations of the design elements. -- Do not change the proportions of any of the design elements or the design itself. You may resize as needed but must retain all proportions. +* Please don't use any other font instead of suggested. +* There should be sufficient clear space around the logo. +* Do not change spacing, alignment, or relative locations of the design elements. +* Do not change the proportions of any of the design elements or the design itself. You may resize as needed but must retain all proportions.