diff --git a/docs/guides/guide-vmanomaly-vmalert.md b/docs/guides/guide-vmanomaly-vmalert.md index 498eede0df..a9f443fc4c 100644 --- a/docs/guides/guide-vmanomaly-vmalert.md +++ b/docs/guides/guide-vmanomaly-vmalert.md @@ -1,4 +1,4 @@ -# vmanomaly Quickstart +# Getting started with vmanomaly **Prerequisites** - In the tutorial, we'll be using the following VictoriaMetrics components: @@ -8,7 +8,7 @@ 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/). -## What is vmanomaly? +## 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. All the service parameters are defined in a config file. @@ -27,11 +27,11 @@ The value is designed to: - *exceed 1* if the datapoint is abnormal. Then, users can enable alerting rules based on the **anomaly score** with [vmalert](#what-is-vmalert). -## What is vmalert? +## 2. What is vmalert? [vmalert](https://docs.victoriametrics.com/vmalert.html) is an alerting tool for VictoriaMetrics. It executes a list of the given alerting or recording rules against configured `-datasource.url`. [Alerting rules](https://docs.victoriametrics.com/vmalert.html#alerting-rules) allow you to define conditions that, when met, will notify the user. The alerting condition is defined in a form of a query expression via [MetricsQL query language](https://docs.victoriametrics.com/MetricsQL.html). For example, in our case, the expression `anomaly_score > 1.0` will notify a user when the calculated anomaly score exceeds a threshold of 1. -## How does vmanomaly works with vmalert? +## 3. How does vmanomaly works with vmalert? Compared to classical alerting rules, anomaly detection is more "hands-off" and data-aware. Instead of thinking of critical conditions to define, user can rely on catching anomalies that were not expected to happen. In other words, by setting up alerting rules, a user must know what to look for, ahead of time, while anomaly detection looks for any deviations from past behavior. Practical use case is to put anomaly score generated by vmanomaly into alerting rules with some threshold. @@ -43,9 +43,10 @@ Practical use case is to put anomaly score generated by vmanomaly into alerting - Explore data for analysis in [Grafana](https://grafana.com/). - Explore vmanomaly results. - Explore vmalert alerts + _____________________________ -## Data to analyze +## 4. Data to analyze Let's talk about data used for anomaly detection in this tutorial. We are going to collect our own CPU usage data with [Node Exporter](https://prometheus.io/docs/guides/node-exporter/) into the VictoriaMetrics database. @@ -73,9 +74,10 @@ Here is how this query may look like in Grafana: ![node_cpu_rate_graph](guide-vmanomaly-node-cpu-rate-graph.png "node_cpu_rate_graph") This query result will generate 8 time series per each cpu, and we will use them as an input for our VM Anomaly Detection. vmanomaly will start learning configured model type separately for each of the time series. + ______________________________ -## vmanomaly configuration and parameter description +## 5. vmanomaly configuration and parameter description **Parameter description**: There are 4 main sections in config file: @@ -141,7 +143,7 @@ writer: _____________________________________________ -## vmanomaly output +## 6. vmanomaly output As the result of running vmanomaly, it produces the following metrics: - `anomaly_score` - the main one. Ideally, if it is between 0.0 and 1.0 it is considered to be a non-anomalous value. If it is greater than 1.0, it is considered an anomaly (but you can reconfigure that in alerting config, of course), - `yhat` - predicted expected value, @@ -154,7 +156,7 @@ Here is an example of how output metric will be written into VictoriaMetrics: ____________________________________________ -## vmalert configuration +## 7. vmalert configuration Here we provide an example of the config for vmalert `vmalert_config.yml`.
@@ -176,7 +178,7 @@ groups: In the query expression we need to put a condition on the generated anomaly scores. Usually if the anomaly score is between 0.0 and 1.0, the analyzed value is not abnormal. The more anomaly score exceeded 1 the more our model is sure that value is an anomaly. You can choose your threshold value that you consider reasonable based on the anomaly score metric, generated by vmanomaly. One of the best ways is to estimate it visually, by plotting the `anomaly_score` metric, along with predicted "expected" range of `yhat_lower` and `yhat_upper`. Later in this tutorial we will show an example ____________________________________________ -## Docker Compose configuration +## 8. Docker Compose configuration Now we are going to configure the `docker-compose.yml` file to run all needed services. Here are all services we are going to run: @@ -375,7 +377,7 @@ docker-compose up -d ___________________________________________________________ -## Model results +## 9. Model results To look at model results we need to go to grafana on the `localhost:3000`. Data vmanomaly need some time to generate more data to visualize. Let's investigate model output visualization in Grafana. @@ -410,5 +412,5 @@ On the page `http://localhost:8880/vmalert/groups` you can find our configured A According to the rule configured for vmalert we will see Alert when anomaly score exceed 1. You will see an alert on Alert tab. `http://localhost:8880/vmalert/alerts` ![alerts](guide-vmanomaly-alerts-firing.png "alerts firing") -## Conclusion +## 10. Conclusion Now we know how to set up Victoria Metric Anomaly Detection tool and use it together with vmalert. We also discovered core vmanomaly generated metrics and behaviour.