From 372553479a727dd81b1e1b19fee5278caa5794e4 Mon Sep 17 00:00:00 2001 From: Daria Karavaieva Date: Fri, 22 Dec 2023 16:06:41 +0100 Subject: [PATCH] docs: vmanomaly guide v1.7.0 changes (#5505) (cherry picked from commit be205013767d3a47162fd2f33af39f8871628db1) --- docs/guides/guide-vmanomaly-vmalert.md | 26 ++++---- docs/vmanomaly.md | 89 +++++++++++++++++++------- 2 files changed, 78 insertions(+), 37 deletions(-) diff --git a/docs/guides/guide-vmanomaly-vmalert.md b/docs/guides/guide-vmanomaly-vmalert.md index c551fc366..196219309 100644 --- a/docs/guides/guide-vmanomaly-vmalert.md +++ b/docs/guides/guide-vmanomaly-vmalert.md @@ -13,12 +13,13 @@ aliases: **Prerequisites** - *vmanomaly* is a part of enterprise package. You can get license key [here](https://victoriametrics.com/products/enterprise/trial) to try this tutorial. - In the tutorial, we'll be using the following VictoriaMetrics components: - - [VictoriaMetrics](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html) (v.1.93.2) - - [vmalert](https://docs.victoriametrics.com/vmalert.html) (v.1.93.2) - - [vmagent](https://docs.victoriametrics.com/vmagent.html) (v.1.93.2) + - [VictoriaMetrics](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html) (v.1.96.0) + - [vmalert](https://docs.victoriametrics.com/vmalert.html) (v.1.96.0) + - [vmagent](https://docs.victoriametrics.com/vmagent.html) (v.1.96.0) If you're unfamiliar with the listed components, please read [QuickStart](https://docs.victoriametrics.com/Quick-Start.html) first. -- It is assumed that you are familiar with [Grafana](https://grafana.com/)(v.9.3.1) and [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/). +- It is assumed that you are familiar with [Grafana](https://grafana.com/)(v.10.2.1) and [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/). + ## 1. What is vmanomaly? *VictoriaMetrics Anomaly Detection* ([vmanomaly](https://docs.victoriametrics.com/vmanomaly.html)) is a service that continuously scans time series stored in VictoriaMetrics and detects unexpected changes within data patterns in real-time. It does so by utilizing user-configurable machine learning models. @@ -90,7 +91,7 @@ ______________________________ ## 5. vmanomaly configuration and parameter description **Parameter description**: -There are 4 main sections in config file: +There are 4 required sections in config file: `scheduler` - defines how often to run and make inferences, as well as what timerange to use to train the model. @@ -113,9 +114,9 @@ Let's look into parameters in each section: Here is the previous 14 days of data to put into the model training. * `model` - * `class` - what model to run. You can use your own model or choose from built-in models: Seasonal Trend Decomposition, Facebook Prophet, ZScore, Rolling Quantile, Holt-Winters and ARIMA. + * `class` - what model to run. You can use your own model or choose from built-in models: Seasonal Trend Decomposition, Facebook Prophet, ZScore, Rolling Quantile, Holt-Winters, Isolation Forest and ARIMA. Here we use Facebook Prophet (`model.prophet.ProphetModel`). - Here we use Facebook Prophet with default parameters (`model.prophet.ProphetModel`). You can put parameters that are available in their [docs](https://facebook.github.io/prophet/docs/quick_start.html). + * `args` - Model specific parameters, represented as YAML dictionary in a simple `key: value` form. For example, you can use parameters that are available in [FB Prophet](https://facebook.github.io/prophet/docs/quick_start.html). * `reader` * `datasource_url` - Data source. An HTTP endpoint that serves `/api/v1/query_range`. @@ -139,7 +140,8 @@ scheduler: model: class: "model.prophet.ProphetModel" - interval_width: 0.98 + args: + interval_width: 0.98 reader: datasource_url: "http://victoriametrics:8428/" @@ -264,7 +266,6 @@ Let's wrap it all up together into the `docker-compose.yml` file.
-{% raw %} ``` yaml services: vmagent: @@ -286,7 +287,7 @@ services: victoriametrics: container_name: victoriametrics - image: victoriametrics/victoria-metrics:v1.93.2 + image: victoriametrics/victoria-metrics:v1.96.0 ports: - 8428:8428 - 8089:8089 @@ -309,7 +310,7 @@ services: grafana: container_name: grafana - image: grafana/grafana-oss:9.3.1 + image: grafana/grafana-oss:10.2.1 depends_on: - "victoriametrics" ports: @@ -346,7 +347,7 @@ services: restart: always vmanomaly: container_name: vmanomaly - image: us-docker.pkg.dev/victoriametrics-test/public/vmanomaly-trial:v1.5.0 + image: us-docker.pkg.dev/victoriametrics-test/public/vmanomaly-trial:v1.7.2 depends_on: - "victoriametrics" ports: @@ -379,7 +380,6 @@ volumes: networks: vm_net: ``` -{% endraw %}
diff --git a/docs/vmanomaly.md b/docs/vmanomaly.md index 152d2b3ea..17f10f355 100644 --- a/docs/vmanomaly.md +++ b/docs/vmanomaly.md @@ -126,43 +126,67 @@ optionally preserving labels). ## Usage -The vmanomaly accepts only one parameter -- config file path: +> Starting from v1.5.0, vmanomaly requires a license key to run. You can obtain a trial license key [here](https://victoriametrics.com/products/enterprise/trial/). -```sh -python3 vmanomaly.py config_zscore.yaml -``` -or -```sh -python3 -m vmanomaly config_zscore.yaml -``` +> See [Getting started guide](https://docs.victoriametrics.com/guides/guide-vmanomaly-vmalert.html). -It is also possible to split up config into multiple files, just list them all in the command line: +### Config file +There are 4 required sections in config file: -```sh -python3 -m vmanomaly model_prophet.yaml io_csv.yaml scheduler_oneoff.yaml +* `scheduler` - defines how often to run and make inferences, as well as what timerange to use to train the model. +* `model` - specific model parameters and configurations, +* `reader` - how to read data and where it is located +* `writer` - where and how to write the generated output. + +[`monitoring`](#monitoring) - defines how to monitor work of *vmanomaly* service. This config section is *optional*. + +#### Config example +Here is an example of config file that will run FB Prophet model, that will be retrained every 2 hours on 14 days of previous data. It will generate inference (including `anomaly_score` metric) every 1 minute. + + +You need to put your datasource urls to use it: + +```yaml +scheduler: + infer_every: "1m" + fit_every: "2h" + fit_window: "14d" + +model: + class: "model.prophet.ProphetModel" + args: + interval_width: 0.98 + +reader: + datasource_url: [YOUR_DATASOURCE_URL] #Example: "http://victoriametrics:8428/" + queries: + cache: "sum(rate(vm_cache_entries))" + +writer: + datasource_url: [YOUR_DATASOURCE_URL] # Example: "http://victoriametrics:8428/" ``` ### Monitoring -vmanomaly can be monitored by using push or pull approach. +*vmanomaly* can be monitored by using push or pull approach. It can push metrics to VictoriaMetrics or expose metrics in Prometheus exposition format. #### Push approach -vmanomaly can push metrics to VictoriaMetrics single-node or cluster version. +*vmanomaly* can push metrics to VictoriaMetrics single-node or cluster version. In order to enable push approach, specify `push` section in config file: ```yaml monitoring: push: - url: "http://victoriametrics:8428/" + url: [YOUR_DATASOURCE_URL] #Example: "http://victoriametrics:8428/" extra_labels: job: "vmanomaly-push" ``` #### Pull approach -vmanomaly can export internal metrics in Prometheus exposition format at `/metrics` page. +*vmanomaly* can export internal metrics in Prometheus exposition format at `/metrics` page. These metrics can be scraped via [vmagent](https://docs.victoriametrics.com/vmagent.html) or Prometheus. In order to enable pull approach, specify `pull` section in config file: @@ -176,10 +200,30 @@ monitoring: This will expose metrics at `http://0.0.0.0:8080/metrics` page. -### Licensing +### Run vmanomaly Docker Container -Starting from v1.5.0 vmanomaly requires a license key to run. You can obtain a trial license -key [here](https://victoriametrics.com/products/enterprise/trial/). +To use *vmanomaly* you need to pull docker image: + +```sh +docker pull us-docker.pkg.dev/victoriametrics-test/public/vmanomaly-trial:latest +``` + +You can put a tag on it for your convinience: + +```sh +docker image tag us-docker.pkg.dev/victoriametrics-test/public/vmanomaly-trial vmanomaly +``` +Here is an example of how to run *vmanomaly* docker container with [license file](#licensing): + +```sh +docker run -it --net [YOUR_NETWORK] \ + -v [YOUR_LICENSE_FILE_PATH]:/license.txt \ + -v [YOUR_CONFIG_FILE_PATH]:/config.yml \ + vmanomaly /config.yml \ + --license-file=/license.txt +``` + +### Licensing The license key can be passed via the following command-line flags: ``` @@ -194,10 +238,7 @@ The license key can be passed via the following command-line flags: verification offline. ``` -Usage example: -``` -python3 -m vmanomaly --license-file /path/to/license_file.yaml config.yaml -``` + In order to make it easier to monitor the license expiration date, the following metrics are exposed(see [Monitoring](#monitoring) section for details on how to scrape them): @@ -212,7 +253,7 @@ vm_license_expires_in_seconds 4.886608e+06 ``` Example alerts for [vmalert](https://docs.victoriametrics.com/vmalert.html): -{% raw %} + ```yaml groups: - name: vm-license @@ -236,4 +277,4 @@ groups: description: "{{ $labels.instance }} of job {{ $labels.job }} license expires in {{ $value | humanizeDuration }}. Please make sure to update the license before it expires." ``` -{% endraw %} +