github-mirrors/VictoriaMetrics
1
0
Fork 0
mirror of https://github.com/VictoriaMetrics/VictoriaMetrics.git synced 2024-11-21 14:44:00 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: vmanomaly guide v1.7.0 changes (#5505)

Browse source 
(cherry picked from commit be20501376)
This commit is contained in:
Daria Karavaieva 2023-12-22 16:06:41 +01:00 committed by hagen1778
parent 2c0cbafc0c
commit 372553479a
No known key found for this signature in database
GPG key ID: 3BF75F3741CA9640
2 changed files with 78 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
docs/guides/guide-vmanomaly-vmalert.md
View file

@ -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.
<div class="with-copy" markdown="1">
{% 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 %}
</div>

89
docs/vmanomaly.md
View file

@ -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 %}