Migration #

Introduction #

This document provides guidelines for migrating to the latest version of VictoriaMetrics Anomaly Detection (vmanomaly). It covers the key changes, compatibility considerations, and best practices to ensure a smooth transition for stateful and stateless modes of operation.

Dry Run #

The --dryRun command-line argument allows Available from v1.27.0 to simulate the migration process without making any actual changes. This is useful for identifying potential issues and understanding the impact of the migration before applying it, e.g. dropping of existing state database or on-disk artifacts for all (or some) of the configured models and data. Starting from version v1.27.0 , the upgrade impact to any new version can be assessed by running vmanomaly with the --dryRun flag automatically. Downgrade check from v1.27.0 (or newer) to earlier versions than v1.25.3 requires setting env variable VMANOMALY_STATE_VERSION_OVERRIDE=<version>, e.g.:

      export VMANOMALY_STATE_VERSION_OVERRIDE=1.25.2
    

Compatibility Matrix #

This section outlines the compatibility of different vmanomaly versions with various components, including data, models, and configuration formats, for both stateful and stateless modes.

Stateful Mode #

For both upgrades and downgrades, assess compatibility at two levels:

• Global compatibility: Whether the target runtime can restore the persisted state as a whole. If globally incompatible, the state must be discarded and rebuilt. Global compatibility alone does not guarantee that every component’s state can be reused.
• Component compatibility: Whether the target runtime can reuse individual components’ persisted artifacts, such as model dumps. A component-specific incompatibility may require migration or discarding and rebuilding only the affected artifacts while retaining the remaining compatible state.

In the tables below, source means the version that wrote the persisted state and target means the version you intend to run, whether newer or older. Compatibility in one direction does not imply compatibility in the reverse direction.

Read each row as source persisted state → target runtime. The upgrade and downgrade tables are separate because compatibility is directional. Apply all relevant boundary rules when crossing several releases. A newer compatibility matrix can describe compatible formats even when an older executable does not recognize the newer provenance version; do not rewrite provenance to bypass that check.

Model availability is a separate check from state compatibility. ARIMA was removed in v1.12.0, before persisted-state restoration existed; remove or replace its configuration when upgrading across that boundary. The mad and zscore aliases redirect to online counterparts from v1.28.4. Prophet, Holt-Winters and Isolation Forest remain available for existing configurations in v1.30.6; planned deprecation is not removal. Always verify the target model catalog and the configuration changes below.

Clearing State #

For releases v1.27.0 and newer, the migration process is automatically handled by vmanomaly when started with settings.restore_state: true, so no manual intervention is required to clear existing state if incompatible.

However, for releases v1.24.0 - v1.26.2 , to clear the existing state (if ended with settings.restore_state: true), please manually delete the existing state database and on-disk artifacts before starting the new version of `vmanomaly - either:

• Manually delete the content of VMANOMALY_MODEL_DUMPS_DIR / VMANOMALY_DATA_DUMPS_DIR folders or
• Set settings.restore_state: false in the config the first run of the new version, then stop vmanomaly, set back settings.restore_state: true, and restart vmanomaly.

Stateless Mode #

In stateless mode, the migration process is almost straightforward as there are no persistent states to manage. One may simply upgrade the vmanomaly service to the latest version and restart it, up to a slight change in the config .YAML files for backward-incompatible changes, see the list below.

Breaking Changes

• v1.12.0 ARIMA model is removed from built-in models . Action: for vmanomaly v1.30.0 and newer, replace ARIMA with Temporal Envelope Available from v1.30.0 ; for older releases, use another supported seasonal model in the models section of the configuration.

• v1.9.0 The sampling_period parameter is now mandatory in VmReader. This change aims to clarify and standardize the frequency of input/output in vmanomaly, thereby reducing uncertainty and aligning with user expectations; Action: Add the sampling_period parameter to your VmReader configuration, e.g.:

        reader:
    # Other VmReader settings...
    sampling_period: 1m
    ...