Quick Start #

For a broader overview please visit the navigation page .

How to install and run vmanomaly #

Note

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

The following options are available:

Note

Anomaly detection models can be kept Available from v1.13.0 on host filesystem after fit stage (instead of default in-memory option); This will drastically reduce RAM for larger configurations. Similar optimization Available from v1.16.0 can be applied to data read from VictoriaMetrics TSDB. See instructions of how to enable it here .

Command-line arguments #

The vmanomaly service supports a set of command-line arguments to configure its behavior, including options for licensing, logging levels, and more.

Note

vmanomaly supports Available from v1.18.5 running on config directories, see the config positional arg description in help message below.

Note

Single-dashed command-line argument Available from v1.23.3 format can be used, e.g. -license.forceOffline in addition to --license.forceOffline. This aligns better with other VictoriaMetrics ecosystem components. Mixing the two styles is also supported, e.g. -license.forceOffline --loggerLevel INFO.

      usage: vmanomaly.py [-h] [--license STRING | --licenseFile PATH] [--license.forceOffline] [--loggerLevel {DEBUG,WARNING,FATAL,ERROR,INFO}] [--watch] [--dryRun] [--outputSpec PATH] 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 {DEBUG,WARNING,FATAL,ERROR,INFO}
                        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.
  --dryRun              Validate only: parse + merge all YAML(s) and run schema checks, then exit. Does not require a license to run. Does not expose metrics, or launch vmanomaly service(s).
  --outputSpec PATH     Target location of .yaml output spec.
    

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

Licensing #

The license key can be specified with the help of the following command-line arguments: --license, --licenseFile, --license.forceOffline

In order to make it easier to monitor the license expiration date, the following metrics are exposed (see Monitoring section for details on how to scrape them):

      # HELP vm_license_expires_at When the license expires as a Unix timestamp in seconds
# TYPE vm_license_expires_at gauge
vm_license_expires_at 1.6963776e+09
# HELP vm_license_expires_in_seconds Amount of seconds until the license expires
# TYPE vm_license_expires_in_seconds gauge
vm_license_expires_in_seconds 4.886608e+06
    

Example alerts for vmalert :

      groups:
  - name: vm-license
    # note the `job` label and update accordingly to your setup
    rules:
      - alert: LicenseExpiresInLessThan30Days
        expr: vm_license_expires_in_seconds < 30 * 24 * 3600
        labels:
          severity: warning
        annotations:
          summary: "{{ $labels.job }} instance {{ $labels.instance }} license expires in less than 30 days"
          description: "{{ $labels.instance }} of job {{ $labels.job }} license expires in {{ $value | humanizeDuration }}. 
            Please make sure to update the license before it expires."

      - alert: LicenseExpiresInLessThan7Days
        expr: vm_license_expires_in_seconds < 7 * 24 * 3600
        labels:
          severity: critical
        annotations:
          summary: "{{ $labels.job }} instance {{ $labels.instance }} license expires in less than 7 days"
          description: "{{ $labels.instance }} of job {{ $labels.job }} license expires in {{ $value | humanizeDuration }}. 
            Please make sure to update the license before it expires."
    

Docker #

Note

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

Due to the upcoming DockerHub pull limits , an additional image registry, Quay.io, has been introduced for VictoriaMetrics images, including vmanomaly . If you encounter pull rate limits, switch from:

      docker pull victoriametrics/vmanomaly:vX.Y.Z

to:

      docker pull quay.io/victoriametrics/vmanomaly:vX.Y.Z

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

Pull Docker image:

      docker pull victoriametrics/vmanomaly:v1.24.0

(Optional step) tag the vmanomaly Docker image:

      docker image tag victoriametrics/vmanomaly:v1.24.0 vmanomaly

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.24.0
    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

Kubernetes with Helm charts #

Note

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

Note

With the forthcoming DockerHub pull limits additional image registry was introduced (quay.io) for VictoriaMetric images, vmanomaly images in particular . If hitting pull limits, try switching your docker pull quay.io/victoriametrics/vmanomaly:vX.Y.Z to docker pull quay.io/victoriametrics/vmanomaly:vX.Y.Z

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

How to configure vmanomaly #

To run vmanomaly, use YAML files or directories containing YAML files. The configuration files support shallow merge, allowing splitting the configuration into multiple files for better organization.

Note

If you are using directories, all .yaml files inside will be shallow merged, without deeper recursion. If you want to merge multiple YAML files, you can specify them as separate arguments, e.g.

          vmanomaly config1.yaml config2.yaml ./config_dir/

Before deploying, check the correctness of your configuration validate config file(s) with --dryRun command-line flag for chosen deployment method (Docker, Kubernetes, etc.). This will parse and merge all YAML files, run schema checks, log errors and warnings (if found) and then exit without starting the service and requiring a license.

Example #

Here is an example of config file that will run Prophet model on vm_cache_entries metric, with periodic scheduler that runs inference every minute and fits the model every day. The model will be trained on the last 2 weeks of data each time it is (re)fitted. The model will produce anomaly_score, yhat, yhat_lower, and yhat_upper series for debugging purposes. The model will be timezone-aware and will use cyclical encoding for the hour of the day and day of the week seasonality.

      settings:
  # https://docs.victoriametrics.com/anomaly-detection/components/settings/
  n_workers: 4  # number of workers to run workload in parallel, set to 0 or negative number to use all available CPU cores
  anomaly_score_outside_data_range: 5.0  # default anomaly score for anomalies outside expected data range
  restore_state: True  # restore state from previous run, available since v1.24.0

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

models:
  # https://docs.victoriametrics.com/anomaly-detection/components/models/#prophet
  prophet_model:
    class: 'prophet'
    provide_series: ['anomaly_score', 'yhat', 'yhat_lower', 'yhat_upper']  # for debugging
    tz_aware: True  # set to True if your data is timezone-aware, to deal with DST changes correctly
    tz_use_cyclical_encoding: True
    tz_seasonalities: # intra-day + intra-week seasonality
      - name: 'hod'  # intra-day seasonality, hour of the day
        fourier_order: 4  # keep it 3-8 based on intraday pattern complexity
        prior_scale: 10
      - name: 'dow'  # intra-week seasonality, time of the week
        fourier_order: 2  # keep it 2-4, as dependencies are learned separately for each weekday
    # inner model args (key-value pairs) accepted by
    # https://facebook.github.io/prophet/docs/quick_start#python-api
    args:
      interval_width: 0.98  # see https://facebook.github.io/prophet/docs/uncertainty_intervals

reader:
  class: 'vm'  # use VictoriaMetrics as a data source
  # 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/victoriametrics/metricsql/
    cache: "sum(rate(vm_cache_entries))"

writer:
  class: 'vm'  # use VictoriaMetrics as a data destination
  # https://docs.victoriametrics.com/anomaly-detection/components/writer/#vm-writer
  datasource_url:  "http://victoriametrics:8428/" # [YOUR_DATASOURCE_URL]
    

Recommended steps #

For optimal service behavior, consider the following tweaks when configuring vmanomaly:

Set settings.n_workers Available from v1.23.0 arg > 1 to utilize more of available CPU cores for parallel workload processing. This can significantly improve performance, especially on larger datasets with a lot of reader.queries and longer scheduler.fit_window intervals. Setting it to zero or negative number will enable using all available CPU cores.
Use on-disk mode Available from v1.13.0 to reduce RAM usage, especially for larger datasets. This mode allows vmanomaly to keep models and the data on the host filesystem after the fit stage, rather than in memory.
Use state restoration Available from v1.24.0 to resume from the last known state for long-term stability. This is controlled by the settings.restore_state boolean arg .

Schedulers:

Configure the inference frequency in the scheduler section of the configuration file.
Ensure that infer_every aligns with your minimum required alerting frequency.
- For example, if receiving alerts every 15 minutes is sufficient (when anomaly_score > 1), set infer_every to match reader.sampling_period or override it per query via reader.queries.query_xxx.step for an optimal setup.

Reader:

Setup the datasource to read data from in the reader section. Include tenant ID if using a cluster version of VictoriaMetrics (multitenant value Available from v1.16.2 can be also used here).
Define queries for input data using MetricsQL under reader.queries section. Note, it’s possible to override reader-level arguments at query level for increased flexibility, e.g. specifying per-query timezone or sampling period .
For longer fit_window intervals in scheduler, consider splitting queries into smaller time ranges to avoid excessive memory usage, timeouts and hitting server-side constraints, so they can be queried separately and reconstructed on vmanomaly side. Please refer to this example for more details.

Writer:

Specify where and how to store anomaly detection metrics in the writer section.
Include tenant ID if using a cluster version of VictoriaMetrics for writing the results.
Adding for label to metric_format argument is recommended for smoother visual experience in the anomaly score dashboard . Please refer to metric_format argument description here .

Models:

Configure built-in models hyperparameters according to your needs in the models section. Where possible, incorporate domain knowledge for optimal results.
(Optional) Develop or integrate your custom models with vmanomaly.
Adding y to provide_series argument values is recommended for smoother visual experience in the anomaly score dashboard . Also, other vmanomaly output series can be specified in provide_series, such as yhat, yhat_lower, yhat_upper, etc. This will allow you to visualize the expected values and their confidence intervals in the dashboard.
Note
Only univariate models support the generation of such output. Other models, such as multivariate or custom , may not support this feature.

Visualization:

Set up anomaly score dashboard to visualize the results of anomaly detection.
Set up self-monitoring dashboard to monitor the health of vmanomaly service and its components.

Check also #

Please refer to the following links for a deeper understanding of Anomaly Detection and vmanomaly:

Next Presets