VictoriaMetrics/docs/anomaly-detection/QuickStart.md
Fred Navruzov ae673e8b34
docs/vmanomaly - release 1.18.5 (#7684)
### Describe Your Changes

docs/vmanomaly - release 1.18.5 doc updates

### Checklist

The following checks are **mandatory**:

- [x] My change adheres [VictoriaMetrics contributing
guidelines](https://docs.victoriametrics.com/contributing/).
2024-11-28 13:50:02 +01:00

8.9 KiB

weight title menu aliases
1 VictoriaMetrics Anomaly Detection Quick Start
docs
parent weight title
anomaly-detection 1 Quick Start
/anomaly-detection/QuickStart.html

For service introduction visit README page and Overview of how vmanomaly works.

How to install and run vmanomaly

To run vmanomaly, you need to have VictoriaMetrics Enterprise license. You can get a trial license key here.

The following options are available:

Note

: Starting from v1.13.0 there is a mode to keep anomaly detection models on host filesystem after fit stage (instead of keeping them in-memory by default); This may lead to noticeable reduction of RAM used on bigger setups. See instructions here.

Note

: Starting from v1.16.0, a similar optimization is available for data read from VictoriaMetrics TSDB. See instructions here.

Command-line arguments

The vmanomaly service supports several command-line arguments to configure its behavior, including options for licensing, logging levels, and more. These arguments can be passed when starting the service via Docker or any other setup. Below is the list of available options:

Note

: Starting from v1.18.5 vmanomaly support running on config directories, see the config positional arg description in help message below.

usage: vmanomaly.py [-h] [--license STRING | --licenseFile PATH] [--license.forceOffline] [--loggerLevel {INFO,DEBUG,ERROR,WARNING,FATAL}] [--watch] config [config ...]

VictoriaMetrics Anomaly Detection Service

positional arguments:
  config                YAML config file(s) or directories containing YAML files. Multiple files will recursively merge each other values so multiple configs can be combined. If a directory
                        is provided, all `.yaml` files inside will be merged, without recursion. Default: vmanomaly.yaml is expected in the current directory.

options:
  -h                    show this help message and exit
  --license STRING      License key for VictoriaMetrics Enterprise. See https://victoriametrics.com/products/enterprise/trial/ to obtain a trial license.
  --licenseFile PATH    Path to file with license key for VictoriaMetrics Enterprise. See https://victoriametrics.com/products/enterprise/trial/ to obtain a trial license.
  --license.forceOffline 
                        Whether to force offline verification for VictoriaMetrics Enterprise license key, which has been passed either via -license or via -licenseFile command-line flag. The
                        issued license key must support offline verification feature. Contact info@victoriametrics.com if you need offline license verification.
  --loggerLevel {INFO,DEBUG,ERROR,WARNING,FATAL}
                        Minimum level to log. Possible values: DEBUG, INFO, WARNING, ERROR, FATAL.
  --watch               [DEPRECATED SINCE v1.11.0] Watch config files for changes. This option is no longer supported and will be ignored.

You can specify these options when running vmanomaly to fine-tune logging levels or handle licensing configurations, as per your requirements.

Docker

To run vmanomaly, you need to have VictoriaMetrics Enterprise license. You can get a trial license key here.

Below are the steps to get vmanomaly up and running inside a Docker container:

  1. Pull Docker image:
docker pull victoriametrics/vmanomaly:v1.18.5
  1. (Optional step) tag the vmanomaly Docker image:
docker image tag victoriametrics/vmanomaly:v1.18.5 vmanomaly
  1. Start the vmanomaly Docker container with a license file, use the command below. Make sure to replace YOUR_LICENSE_FILE_PATH, and YOUR_CONFIG_FILE_PATH with your specific details:
export YOUR_LICENSE_FILE_PATH=path/to/license/file
export YOUR_CONFIG_FILE_PATH=path/to/config/file
docker run -it -v $YOUR_LICENSE_FILE_PATH:/license \
               -v $YOUR_CONFIG_FILE_PATH:/config.yml \
               vmanomaly /config.yml \
               --licenseFile=/license \
               --loggerLevel=INFO

In case you found PermissionError: [Errno 13] Permission denied: in vmanomaly logs, set user/user group to 1000 in the run command above / in a docker-compose file:

export YOUR_LICENSE_FILE_PATH=path/to/license/file
export YOUR_CONFIG_FILE_PATH=path/to/config/file
docker run -it --user 1000:1000 \
               -v $YOUR_LICENSE_FILE_PATH:/license \
               -v $YOUR_CONFIG_FILE_PATH:/config.yml \
               vmanomaly /config.yml \
               --licenseFile=/license \
               --loggerLevel=INFO
# docker-compose file
services:
  # ...
  vmanomaly:
    image: victoriametrics/vmanomaly:v1.18.5
    volumes:
        $YOUR_LICENSE_FILE_PATH:/license
        $YOUR_CONFIG_FILE_PATH:/config.yml
    command:
      - "/config.yml"
      - "--licenseFile=/license"
      - "--loggerLevel=INFO"
    # ...

For a complete docker-compose example please refer to our alerting guide, chapter docker-compose

See also:

Kubernetes with Helm charts

To run vmanomaly, you need to have VictoriaMetrics Enterprise license. You can get a trial license key here.

You can run vmanomaly in Kubernetes environment with these Helm charts.

How to configure vmanomaly

To run vmanomaly you need to set up configuration file in yaml format.

Here is an example of config file that will run Facebook 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.

schedulers:
  2h_1m:
    # https://docs.victoriametrics.com/anomaly-detection/components/scheduler/#periodic-scheduler
    class: 'periodic'
    infer_every: '1m'
    fit_every: '2h'
    fit_window: '2w'

models:
  # https://docs.victoriametrics.com/anomaly-detection/components/models/#prophet
  prophet_model:
    class: "prophet"  # or "model.prophet.ProphetModel" until v1.13.0
    args:
      interval_width: 0.98

reader:
  # https://docs.victoriametrics.com/anomaly-detection/components/reader/#vm-reader
  datasource_url: "http://victoriametrics:8428/" # [YOUR_DATASOURCE_URL]
  sampling_period: "1m"
  queries: 
    # define your queries with MetricsQL - https://docs.victoriametrics.com/metricsql/
    cache: "sum(rate(vm_cache_entries))"

writer:
  # https://docs.victoriametrics.com/anomaly-detection/components/writer/#vm-writer
  datasource_url:  "http://victoriametrics:8428/" # [YOUR_DATASOURCE_URL]

Next steps:

  • Define how often to run and make inferences in the scheduler section of a config file.
  • Setup the datasource to read data from in the reader section.
  • Specify where and how to store anomaly detection metrics in the writer section.
  • Configure built-in models parameters according to your needs in the models section.
  • Integrate your custom models with vmanomaly.
  • Define queries for input data using MetricsQL.

Check also

Here are other materials that you might find useful: