From 0d5b36d8bae98789878679d632fc62a4e95662ad Mon Sep 17 00:00:00 2001 From: Mathias Palmersheim Date: Fri, 26 Jul 2024 11:42:30 -0500 Subject: [PATCH] Updated docs --- docs/vmagent.md | 16 +++++- docs/vmalert.md | 50 +++++++++++++++- docs/vmauth.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 210 insertions(+), 6 deletions(-) diff --git a/docs/vmagent.md b/docs/vmagent.md index da51de1aff..6b76a519ed 100644 --- a/docs/vmagent.md +++ b/docs/vmagent.md @@ -160,7 +160,8 @@ sudo systemctl status vmagent 10. Check for data in VMUI To make sure scrape jobs are working and sending data to VictoriaMetrics go to `http://:8428/vmui` type `{job=vmagent_quickstart"}` in the query box and click `Execute Query`. -If you see data the vmagent is successfully evaluating recording rules and sending the data to VictoriaMetrics +If you see data the vmagent is successfully evaluating recording rules and sending the data to VictoriaMetrics. +If you are not using VictoriaMetrics you can run the query `{job="vmagent_quickstart"}` in the explore page of Grafana or in Promethues UI. ### CLI Please download `vmutils-*` archive from [releases page](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/latest) ( @@ -190,11 +191,15 @@ Example command for scraping Prometheus targets and writing the data to single-n The container image for vmagent can be found on [docker hub](https://hub.docker.com/r/victoriametrics/vmagent/tags) and will also work with other OCI compatible runtimes like podman. + +1. Create scrape configuration. + + To scrape data we need to create config file with that defines our scrape job. You can use an existing Promethues scrape config or you add this sample one to `./vmgaent/scrape.yml` ```sh -cat< ./vmagent/scrape.yml +mkdir -p ./vmagent && cat< ./vmagent/scrape.yml scrape_configs: - job_name: vmagent_quickstart scrape_interval: 30s @@ -205,14 +210,19 @@ scrape_configs: END ``` -Now we can run the container +2. Run the Container ```sh docker run -p 8429:8429 -v ./vmagent:/vmagent docker.io/victoriametrics/vmagent -remoteWrite.tmpDataPath=/vmagent -promscrape.config=/vmagent/scrape.yml -remoteWrite.url=http://victoria-metrics-host:8428/api/v1/write ``` + +3. Verify Scrape Job is working. + + If you don't see errors in the command line after 30 seconds check VMUI to confirm data is flowing from `vmagent` to victoriametrics by going to `http://victoria-metrics-host:8428/vmui`. Then type `{job="vmagent_quickstart"}` and press the `execute query` button and if everything is working you see some metrics. +If you are not using VictoriaMetrics you can run the query `{job="vmagent_quickstart"}` in the explore page of Grafana or in Promethues UI. diff --git a/docs/vmalert.md b/docs/vmalert.md index 53b47647c8..d688f3196a 100644 --- a/docs/vmalert.md +++ b/docs/vmalert.md @@ -51,6 +51,9 @@ Use this feature for the following cases: ## QuickStart +This quickstart guide assumes you have Victoriametrics single configured and it's metric endpoint is being scraped. +If this assumption is not the case for you please replace `vm_cache_entries{type="storage/hour_metric_ids"}` with a query that returns data. + ### Linux Service 1. Download the `vmutils` binary for your platform from [GitHub](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/latest) @@ -80,7 +83,7 @@ mkdir -p /var/lib/victoria-metrics/vmalert/rules && chown -R victoriametrics:vic ```sh cat </etc/systemd/system/vmalert.service [Unit] -Description=Description=VictoriaMetrics VMalert service +Description=Description=VictoriaMetrics vmalert service After=network.target [Service] @@ -108,7 +111,7 @@ Extra [command-line flags](https://docs.victoriametrics.com/vmalert/#advanced-us ```sh cat </var/lib/victoria-metrics/vmalert/rules/quickstart.yml groups: - - name: mean site latency + - name: max active series limit: 0 interval: 2m # how often rule is evaluated rules: @@ -141,10 +144,51 @@ sudo systemctl status vmalert To make sure recording rules are being evaluated and sending data to VictoriaMetrics go to `http://victoriametrics_ip_or_hostname>:8428/vmui` type `victoriametrics:max:active:series:1d` in the query box and click `Execute Query`. If you see data the vmalert is successfully evaluating recording rules and sending the data to VictoriaMetrics - +If you are not using VictoriaMetrics you can run the query `victoriametrics:max:active:series:1d` in the explore page of Grafana or in Promethues UI. ### Docker +The container image for vmalert can be found on [docker hub](https://hub.docker.com/r/victoriametrics/vmalert/tags) and will also work with other OCI compatible runtimes like podman. + + +1. Create Recording Rule + +Run the command below to create a configuration file with a single recording rule. +You can also add use an existing Prometheus recording rule file as well. + +```sh +mkdir -p ./vmalert/rules && cat <./vmalert/rules/quickstart.yml +groups: + - name: max active series + limit: 0 + interval: 2m # how often rule is evaluated + rules: + - record: victoriametrics:max:active:series:1d # metric to record results to for recording rules it is best practice separate words with : instead of _ + expr: | + vm_cache_entries{type="storage/hour_metric_ids"} # query to collect data from + labels: # key value pairs that are added as labels to the metrics generated by the query + service: "victoriametrics" +END +``` + +2. Run the container + + +Run the command below after replacing `:8428` with your VictoriaMetrics or Prometheus remote write URL + + +```sh +docker run -p 9093:9093 -v ./vmalert:/vmalert docker.io/victoriametrics/vmalert -datasource.url=http://:8428 -remoteWrite.url=http://:8428 -remoteRead.url=http://:8428 -httpListenAddr=0.0.0.0:9093 -rule=/vmalert/rules/*.yaml -rule=/vmalert/rules/*.yml -configCheckInterval=1m + +``` + +3. Verify Recording rules are working. + +To verify if `vmalert` is running run `curl http://localhost:9093/health` and you should get OK as the response. + +If you don't see errors in the command line after 30 seconds check VMUI to confirm recording rules are working and sending to VictoriaMetrics to `http://victoria-metrics-host:8428/vmui`. +Then type `victoriametrics:max:active:series:1d` and press the `execute query` button and if everything is working you see some metrics. +If you are not using VictoriaMetrics you can run the query `victoriametrics:max:active:series:1d` in the explore page of Grafana or in Promethues UI. ### Build from Source To build `vmalert` from sources: diff --git a/docs/vmauth.md b/docs/vmauth.md index 5a798c2291..32393582e7 100644 --- a/docs/vmauth.md +++ b/docs/vmauth.md @@ -14,6 +14,156 @@ or any other HTTP backends. ## Quick start + +### Linux Service +1. Download the `vmutils` binary for your platform from [GitHub](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/latest) + +2. Extract vmutils to /usr/local/bin by running + +```sh +sudo tar -xvf -C /usr/local/bin +``` + +Replace `` with the archive you downloaded in step 1. + +3. create a VictoriaMetrics user + +```sh +sudo useradd -s /usr/sbin/nologin victoriametrics +``` + +4. Create a folder for storing the vmauth config + +```sh +mkdir -p /var/lib/victoria-metrics/vmauth && chown -R victoriametrics:victoriametrics /var/lib/victoria-metrics/vmauth +``` + + +5. Create a Linux Service by running the following command replace + +```sh +cat </etc/systemd/system/vmauth.service +[Unit] +Description=Description=VictoriaMetrics vmauth service +After=network.target + +[Service] +Type=simple +User=victoriametrics +Group=victoriametrics +ExecStart=/usr/local/bin/vmauth-prod -auth.config=/var/lib/victoria-metrics/vmauth/auth.yaml +SyslogIdentifier=vmauth +Restart=always + +PrivateTmp=yes +ProtectHome=yes +NoNewPrivileges=yes + +ProtectSystem=full +[Install] +WantedBy=multi-user.target +END +``` +Extra [command-line flags](https://docs.victoriametrics.com/vmauth/#advanced-usage) can be added to the `ExecStart` line and the [data ingestion docs](https://docs.victoriametrics.com/data-ingestion/vmauth/) have details for connecting to Victoriametrics with encryption and authentication. + +6. Create a `vmauth` config + +Run the command below after changing `` to the ip or hostname of your victoriametrics server. + +```sh +cat </var/lib/victoria-metrics/vmauth/auth.yaml +users: + - username: "victoria" + password: "metrics" + url_prefix: "http://:8428" + - bearer_token: "victoria-metrics" + url_prefix: "http://:8428" +END +``` + +7. Start and enable the service + + +```sh +sudo systemctl daemon-reload && sudo systemctl enable --now vmauth.service +``` + + +8. Check that service is running + +```sh +sudo systemctl status vmauth +``` + +9. Test Basic Authentication by running + +Run the following command to make sure basic authentication is working. + +```sh +curl --head -u 'victoria:metrics' http://:8427/vmui/ +``` + +If everything is working you will get `HTTP1.1 200 OK` in the first line of the output. + +10. Test Bearer Token + +Run the following command to test that bearer authentication is working + +```sh +curl -H 'Authorization Bearer victoria-metrics' http://:8427/vmui +``` + +If everything is working you will get `HTTP1.1 200 OK` in the first line of the output. + + +### Docker + +The container image for vmauth can be found on [docker hub](https://hub.docker.com/r/victoriametrics/vmauth/tags) and will also work with other OCI compatible runtimes like podman. + +1. Create `vmauth` config + + +Create a vmauth configuration by running the command below fater changing `victoriametrics_ip_or_hostname` to the ip or hostname of your victoriametrics instance. + +```sh +mkdir -p ./vmauth && cat <./vmauth/auth.yaml +users: + - username: "victoria" + password: "metrics" + url_prefix: "http://:8428" + - bearer_token: "victoria-metrics" + url_prefix: "http://:8428" +END +``` + +2. Run the container + +```sh +docker run -p 8427:8427 -v ./vmauth:/vmauth docker.io/victoriametrics/vmauth -auth.config /vmauth/config.yaml +``` + +3. Test Basic Authentication by running + +Run the following command to make sure basic authentication is working. + +```sh +curl --head -u 'victoria:metrics' http://:8427/vmui/ +``` + +If everything is working you will get `HTTP1.1 200 OK` in the first line of the output. + +4. Test Bearer Token + +Run the following command to test that bearer authentication is working + +```sh +curl -H 'Authorization Bearer victoria-metrics' http://:8427/vmui +``` + +If everything is working you will get `HTTP1.1 200 OK` in the first line of the output. + + +### CLI Just download `vmutils-*` archive from [releases page](https://github.com/VictoriaMetrics/VictoriaMetrics/releases/latest), unpack it and pass the following flag to `vmauth` binary in order to start authorizing and proxying requests: