From 9d19c2d89b9ade61ca6c2c212a0d582984410b51 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Fri, 24 Mar 2023 13:03:54 -0700 Subject: [PATCH] docs/vmagent.md: clarify that there is no need to specify multiple -remoteWrite.url options when writing data to a single VictoriaMetrics cluster when data replication is needed Also add a link to https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format from `getting started` section, so users could quickly find how to write data to VictoriaMetrics cluster --- app/vmagent/README.md | 32 ++++++++++++++++++++------------ docs/vmagent.md | 32 ++++++++++++++++++++------------ 2 files changed, 40 insertions(+), 24 deletions(-) diff --git a/app/vmagent/README.md b/app/vmagent/README.md index b6b954354c..0f9c47abdb 100644 --- a/app/vmagent/README.md +++ b/app/vmagent/README.md @@ -54,10 +54,19 @@ and sending the data to the Prometheus-compatible remote storage: The path can point either to local file or to http url. `vmagent` doesn't support some sections of Prometheus config file, so you may need either to delete these sections or to run `vmagent` with `-promscrape.config.strictParse=false` command-line flag. In this case `vmagent` ignores unsupported sections. See [the list of unsupported sections](#unsupported-prometheus-config-sections). -* `-remoteWrite.url` with Prometheus-compatible remote storage endpoint such as VictoriaMetrics, the `-remoteWrite.url` argument can be specified - multiple times to replicate data concurrently to multiple remote storage systems. See [various use cases](#use-cases). +* `-remoteWrite.url` with Prometheus-compatible remote storage endpoint such as VictoriaMetrics. -Example command line: +Example command for writing the data recieved via [supported push-based protocols](#how-to-push-data-to-vmagent) +to [single-node VictoriaMetrics](https://docs.victoriametrics.com/) located at `victoria-metrics-host:8428`: + +```console +/path/to/vmagent -remoteWrite.url=https://victoria-metrics-host:8428/api/v1/write +``` + +See [these docs](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) if you need writing +the data to [VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html). + +Example command for scraping Prometheus targets and writing the data to single-node VictoriaMetrics: ```console /path/to/vmagent -promscrape.config=/path/to/prometheus.yml -remoteWrite.url=https://victoria-metrics-host:8428/api/v1/write @@ -68,18 +77,12 @@ See [how to scrape Prometheus-compatible targets](#how-to-collect-metrics-in-pro If you use single-node VictoriaMetrics, then you can discover and scrape Prometheus-compatible targets directly from VictoriaMetrics without the need to use `vmagent` - see [these docs](https://docs.victoriametrics.com/#how-to-scrape-prometheus-exporters-such-as-node-exporter). -If you don't need to scrape Prometheus-compatible targets, then the `-promscrape.config` option isn't needed. -For example, the following command is sufficient for accepting data via [supported push-based protocols](#how-to-push-data-to-vmagent) -and sending it to the provided `-remoteWrite.url`: - -```console -/path/to/vmagent -remoteWrite.url=https://victoria-metrics-host:8428/api/v1/write -``` - -`vmagent` can save network bandwidth usage costs under high load when [VictoriaMetrics remote write protocol is enabled](#victoriametrics-remote-write-protocol). +`vmagent` can save network bandwidth usage costs under high load when [VictoriaMetrics remote write protocol is used](#victoriametrics-remote-write-protocol). See [troubleshooting docs](#troubleshooting) if you encounter common issues with `vmagent`. +See [various use cases](#use-cases) for vmagent. + Pass `-help` to `vmagent` in order to see [the full list of supported command-line flags with their descriptions](#advanced-usage). ## How to push data to vmagent @@ -151,6 +154,11 @@ If a single remote storage instance temporarily is out of service, then the coll `vmagent` buffers the collected data in files at `-remoteWrite.tmpDataPath` until the remote storage becomes available again and then it sends the buffered data to the remote storage in order to prevent data gaps. +[VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html) already supports replication, +so there is no need in specifying multiple `-remoteWrite.url` flags when writing data to the same cluster. +See [these docs](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#replication-and-data-safety). + + ### Relabeling and filtering `vmagent` can add, remove or update labels on the collected data before sending it to the remote storage. Additionally, diff --git a/docs/vmagent.md b/docs/vmagent.md index 92f68de859..cebfaac04f 100644 --- a/docs/vmagent.md +++ b/docs/vmagent.md @@ -58,10 +58,19 @@ and sending the data to the Prometheus-compatible remote storage: The path can point either to local file or to http url. `vmagent` doesn't support some sections of Prometheus config file, so you may need either to delete these sections or to run `vmagent` with `-promscrape.config.strictParse=false` command-line flag. In this case `vmagent` ignores unsupported sections. See [the list of unsupported sections](#unsupported-prometheus-config-sections). -* `-remoteWrite.url` with Prometheus-compatible remote storage endpoint such as VictoriaMetrics, the `-remoteWrite.url` argument can be specified - multiple times to replicate data concurrently to multiple remote storage systems. See [various use cases](#use-cases). +* `-remoteWrite.url` with Prometheus-compatible remote storage endpoint such as VictoriaMetrics. -Example command line: +Example command for writing the data recieved via [supported push-based protocols](#how-to-push-data-to-vmagent) +to [single-node VictoriaMetrics](https://docs.victoriametrics.com/) located at `victoria-metrics-host:8428`: + +```console +/path/to/vmagent -remoteWrite.url=https://victoria-metrics-host:8428/api/v1/write +``` + +See [these docs](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) if you need writing +the data to [VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html). + +Example command for scraping Prometheus targets and writing the data to single-node VictoriaMetrics: ```console /path/to/vmagent -promscrape.config=/path/to/prometheus.yml -remoteWrite.url=https://victoria-metrics-host:8428/api/v1/write @@ -72,18 +81,12 @@ See [how to scrape Prometheus-compatible targets](#how-to-collect-metrics-in-pro If you use single-node VictoriaMetrics, then you can discover and scrape Prometheus-compatible targets directly from VictoriaMetrics without the need to use `vmagent` - see [these docs](https://docs.victoriametrics.com/#how-to-scrape-prometheus-exporters-such-as-node-exporter). -If you don't need to scrape Prometheus-compatible targets, then the `-promscrape.config` option isn't needed. -For example, the following command is sufficient for accepting data via [supported push-based protocols](#how-to-push-data-to-vmagent) -and sending it to the provided `-remoteWrite.url`: - -```console -/path/to/vmagent -remoteWrite.url=https://victoria-metrics-host:8428/api/v1/write -``` - -`vmagent` can save network bandwidth usage costs under high load when [VictoriaMetrics remote write protocol is enabled](#victoriametrics-remote-write-protocol). +`vmagent` can save network bandwidth usage costs under high load when [VictoriaMetrics remote write protocol is used](#victoriametrics-remote-write-protocol). See [troubleshooting docs](#troubleshooting) if you encounter common issues with `vmagent`. +See [various use cases](#use-cases) for vmagent. + Pass `-help` to `vmagent` in order to see [the full list of supported command-line flags with their descriptions](#advanced-usage). ## How to push data to vmagent @@ -155,6 +158,11 @@ If a single remote storage instance temporarily is out of service, then the coll `vmagent` buffers the collected data in files at `-remoteWrite.tmpDataPath` until the remote storage becomes available again and then it sends the buffered data to the remote storage in order to prevent data gaps. +[VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html) already supports replication, +so there is no need in specifying multiple `-remoteWrite.url` flags when writing data to the same cluster. +See [these docs](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#replication-and-data-safety). + + ### Relabeling and filtering `vmagent` can add, remove or update labels on the collected data before sending it to the remote storage. Additionally,