From ea5904fd76c129c54eb2f72fee372fa57526f032 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Wed, 4 Mar 2020 17:42:20 +0200 Subject: [PATCH] app/vmagent/README.md: add `use cases` section --- app/vmagent/README.md | 35 +++++++++++++++++++++++++++++++- docs/vmagent.md | 46 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 72 insertions(+), 9 deletions(-) diff --git a/app/vmagent/README.md b/app/vmagent/README.md index 1530b02cb0..9ad38857b0 100644 --- a/app/vmagent/README.md +++ b/app/vmagent/README.md @@ -60,7 +60,40 @@ Then send Influx data to `http://vmagent-host:8429/write`. See [these docs](http Pass `-help` to `vmagent` in order to see the full list of supported command-line flags with their descriptions. -### How to collect metrics in Prometheus format? +### Use cases + +#### Drop-in replacement for Prometheus + +If you use Prometheus only for scraping metrics from various targets and forwarding these metrics to remote storage, +then `vmagent` can replace such Prometheus setup. Usually `vmagent` requires lower amounts RAM, CPU and network bandwidth comparing to Prometheus for such setup. +See [these docs](#how-to-collect-metrics-in-prometheus-format) for details. + + +#### Replication and high availability + +`vmagent` replicates the collected metrics among multiple remote storage instances configured via `-remoteWrite.url` args. +If a single remote storage instance temporarily goes out of service, then the collected data remains available in another remote storage instances. +`vmagent` buffers the collected data in files at `-remoteWrite.tmpDataPath` until the remote storage becomes available again. +Then it sends the buffered data to the remote storage in order to prevent data gaps in the remote storage. + + +#### Relabeling and filtering + +`vmagent` can add, remove or update labels on the collected data before sending it to remote storage. Additionally, +it can remove unneeded samples via Prometheus-like relabeling before sending the collected data to remote storage. +See [these docs](#relabeling) for details. + + +#### Splitting data streams among multiple systems + +`vmagent` supports splitting of the collected data among muliple destinations with the help of `-remoteWrite.urlRelabelConfig`, +which is applied independently for each configured `-remoteWrite.url` destination. For instance, it is possible to replicate or split +data among long-term remote storage, short-term remote storage and real-time analytical system [built on top of Kafka](https://github.com/Telefonica/prometheus-kafka-adapter). +Note that each destination can receive its own subset of the collected data thanks to per-destination relabeling via `-remoteWrite.urlRelabelConfig`. + + + +### How to collect metrics in Prometheus format Pass the path to `prometheus.yml` to `-promscrape.config` command-line flag. `vmagent` takes into account the following sections from [Prometheus config file](https://prometheus.io/docs/prometheus/latest/configuration/configuration/): diff --git a/docs/vmagent.md b/docs/vmagent.md index 3cf3c85a75..9ad38857b0 100644 --- a/docs/vmagent.md +++ b/docs/vmagent.md @@ -28,7 +28,7 @@ to `vmagent` (like the ability to push metrics instead of pulling them). We did * Can replicate collected metrics simultaneously to multiple remote storage systems. * Works in environments with unstable connections to remote storage. If the remote storage is unavailable, the collected metrics are buffered at `-remoteWrite.tmpDataPath`. The buffered metrics are sent to remote storage as soon as connection - to remote storage is recovered. + to remote storage is recovered. The maximum disk usage for the buffer can be limited with `-remoteWrite.maxDiskUsagePerURL`. * Uses lower amounts of RAM, CPU, disk IO and network bandwidth comparing to Prometheus. @@ -60,7 +60,40 @@ Then send Influx data to `http://vmagent-host:8429/write`. See [these docs](http Pass `-help` to `vmagent` in order to see the full list of supported command-line flags with their descriptions. -### How to collect metrics in Prometheus format? +### Use cases + +#### Drop-in replacement for Prometheus + +If you use Prometheus only for scraping metrics from various targets and forwarding these metrics to remote storage, +then `vmagent` can replace such Prometheus setup. Usually `vmagent` requires lower amounts RAM, CPU and network bandwidth comparing to Prometheus for such setup. +See [these docs](#how-to-collect-metrics-in-prometheus-format) for details. + + +#### Replication and high availability + +`vmagent` replicates the collected metrics among multiple remote storage instances configured via `-remoteWrite.url` args. +If a single remote storage instance temporarily goes out of service, then the collected data remains available in another remote storage instances. +`vmagent` buffers the collected data in files at `-remoteWrite.tmpDataPath` until the remote storage becomes available again. +Then it sends the buffered data to the remote storage in order to prevent data gaps in the remote storage. + + +#### Relabeling and filtering + +`vmagent` can add, remove or update labels on the collected data before sending it to remote storage. Additionally, +it can remove unneeded samples via Prometheus-like relabeling before sending the collected data to remote storage. +See [these docs](#relabeling) for details. + + +#### Splitting data streams among multiple systems + +`vmagent` supports splitting of the collected data among muliple destinations with the help of `-remoteWrite.urlRelabelConfig`, +which is applied independently for each configured `-remoteWrite.url` destination. For instance, it is possible to replicate or split +data among long-term remote storage, short-term remote storage and real-time analytical system [built on top of Kafka](https://github.com/Telefonica/prometheus-kafka-adapter). +Note that each destination can receive its own subset of the collected data thanks to per-destination relabeling via `-remoteWrite.urlRelabelConfig`. + + + +### How to collect metrics in Prometheus format Pass the path to `prometheus.yml` to `-promscrape.config` command-line flag. `vmagent` takes into account the following sections from [Prometheus config file](https://prometheus.io/docs/prometheus/latest/configuration/configuration/): @@ -69,11 +102,7 @@ sections from [Prometheus config file](https://prometheus.io/docs/prometheus/lat * `scrape_configs` All the other sections are ignored, including [remote_write](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write) section. -Use `-remoteWrite.*` command-line flags instead for configuring remote write settings: - -* `-remoteWrite.url` for pointing to remote storage. Data to remote storage can be sent either via HTTP or HTTPS. See `-remoteWrite.tls*` flags for details. -* `-remoteWrite.label` for adding labels to metrics before sending them to remote storage. -* `-remoteWrite.relabelConfig` for applying relabeling to metrics before sending them to remote storage. +Use `-remoteWrite.*` command-line flags instead for configuring remote write settings. The following scrape types in [scrape_config](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) section are supported: @@ -114,7 +143,8 @@ The relabeling can be defined in the following places: * At `scrape_config -> relabel_configs` section in `-promscrape.config` file. This relabeling is applied to targets when parsing the file during `vmagent` startup or during config reload after sending `SIGHUP` signal to `vmagent` via `kill -HUP`. * At `scrape_config -> metric_relabel_configs` section in `-promscrape.config` file. This relabeling is applied to metrics after each scrape for the configured targets. -* At `-remoteWrite.relabelConfig` file. This relabeling is aplied to all the collected metrics before sending them to `-remoteWrite.url`. +* At `-remoteWrite.relabelConfig` file. This relabeling is aplied to all the collected metrics before sending them to remote storage. +* At `-remoteWrite.urlRelabelConfig` files. This relabeling is applied to metrics before sending them to the corresponding `-remoteWrite.url`. Read more about relabeling in the following articles: