Stateless ADTK detector plugin

The ADTK Anomaly Detector Plugin provides advanced time series anomaly detection for InfluxDB 3 using the ADTK (Anomaly Detection Toolkit) library. Apply statistical and machine learning-based detection methods to identify outliers, level shifts, volatility changes, and seasonal anomalies in your data. Features consensus-based detection requiring multiple detectors to agree before triggering alerts, reducing false positives.

Configuration

Required parameters

Advanced parameters

Notification parameters

Supported ADTK detectors

TOML configuration

To use a TOML configuration file, set the PLUGIN_DIR environment variable and specify the config_file_path in the trigger arguments. This is in addition to the --plugin-dir flag when starting InfluxDB 3.

Example TOML configuration

adtk_anomaly_config_scheduler.toml

For more information on using TOML configuration files, see the Using TOML Configuration Files section in the influxdb3_plugins /README.md.

Installation

1. Start InfluxDB 3 Enterprise with the Processing Engine enabled (--plugin-dir /path/to/plugins)

2. Install required Python packages:

   • requests (for HTTP requests)
   • adtk (for anomaly detection)
   • pandas (for data manipulation)

   influxdb3 install package requests
   influxdb3 install package adtk
   influxdb3 install package pandas

Create trigger

Create a scheduled trigger for anomaly detection:

influxdb3 create trigger \
  --database mydb \
  --plugin-filename adtk_anomaly_detection_plugin.py \
  --trigger-spec "every:10m" \
  --trigger-arguments "measurement=cpu,field=usage,detectors=QuantileAD.LevelShiftAD,detector_params=eyJRdWFudGlsZUFKIjogeyJsb3ciOiAwLjA1LCAiaGlnaCI6IDAuOTV9LCAiTGV2ZWxTaGlmdEFKIjogeyJ3aW5kb3ciOiA1fX0=,window=10m,senders=slack,slack_webhook_url=https://hooks.slack.com/services/..." \
  anomaly_detector

Enable trigger

influxdb3 enable trigger --database mydb anomaly_detector

Examples

Basic anomaly detection

Detect outliers using quantile-based detection:

# Base64 encode detector parameters: {"QuantileAD": {"low": 0.05, "high": 0.95}}
echo '{"QuantileAD": {"low": 0.05, "high": 0.95}}' | base64

influxdb3 create trigger \
  --database sensors \
  --plugin-filename adtk_anomaly_detection_plugin.py \
  --trigger-spec "every:5m" \
  --trigger-arguments "measurement=temperature,field=value,detectors=QuantileAD,detector_params=eyJRdWFudGlsZUFKIjogeyJsb3ciOiAwLjA1LCAiaGlnaCI6IDAuOTV9fQ==,window=1h,senders=slack,slack_webhook_url=https://hooks.slack.com/services/..." \
  temp_anomaly_detector

Multi-detector consensus

Use multiple detectors with consensus requirement:

# Base64 encode: {"QuantileAD": {"low": 0.1, "high": 0.9}, "LevelShiftAD": {"window": 10}}
echo '{"QuantileAD": {"low": 0.1, "high": 0.9}, "LevelShiftAD": {"window": 10}}' | base64

influxdb3 create trigger \
  --database monitoring \
  --plugin-filename adtk_anomaly_detection_plugin.py \
  --trigger-spec "every:15m" \
  --trigger-arguments "measurement=cpu_metrics,field=utilization,detectors=QuantileAD.LevelShiftAD,detector_params=eyJRdWFudGlsZUFEIjogeyJsb3ciOiAwLjEsICJoaWdoIjogMC45fSwgIkxldmVsU2hpZnRBRCI6IHsid2luZG93IjogMTB9fQ==,min_consensus=2,window=30m,senders=discord,discord_webhook_url=https://discord.com/api/webhooks/..." \
  cpu_consensus_detector

Volatility shift detection

Monitor for sudden changes in data volatility:

# Base64 encode: {"VolatilityShiftAD": {"window": 20}}
echo '{"VolatilityShiftAD": {"window": 20}}' | base64

influxdb3 create trigger \
  --database trading \
  --plugin-filename adtk_anomaly_detection_plugin.py \
  --trigger-spec "every:1m" \
  --trigger-arguments "measurement=stock_prices,field=price,detectors=VolatilityShiftAD,detector_params=eyJWb2xhdGlsaXR5U2hpZnRBRCI6IHsid2luZG93IjogMjB9fQ==,window=1h,min_condition_duration=5m,senders=sms,twilio_from_number=+1234567890,twilio_to_number=+0987654321" \
  volatility_detector

Features

• Advanced detection methods: Multiple ADTK detectors for different anomaly types
• Consensus-based filtering: Reduce false positives with multi-detector agreement
• Configurable persistence: Require anomalies to persist before alerting
• Multi-channel notifications: Integration with various notification channels
• Template messages: Customizable notification templates with dynamic variables
• Flexible scheduling: Configurable detection intervals and time windows

Troubleshooting

Common issues

Detector parameter encoding

• Ensure detector_params is valid Base64-encoded JSON
• Use command line Base64 encoding: echo '{"QuantileAD": {"low": 0.05}}' | base64
• Verify JSON structure matches detector requirements

False positive notifications

• Increase min_consensus to require more detectors to agree
• Add min_condition_duration to require anomalies to persist
• Adjust detector-specific thresholds in detector_params

Missing dependencies

• Install required packages: adtk, pandas, requests
• Ensure the Notifier Plugin is installed for notifications

Data quality issues

• Verify sufficient data points in the specified window
• Check for null values or data gaps that affect detection
• Ensure field contains numeric data suitable for analysis

Base64 parameter encoding

Generate properly encoded detector parameters:

# Single detector
echo '{"QuantileAD": {"low": 0.05, "high": 0.95}}' | base64 -w 0

# Multiple detectors
echo '{"QuantileAD": {"low": 0.1, "high": 0.9}, "LevelShiftAD": {"window": 15}}' | base64 -w 0

# Threshold detector
echo '{"ThresholdAD": {"high": 100, "low": 10}}' | base64 -w 0

Message template variables

Available variables for notification templates:

• $table: Measurement name
• $field: Field name with anomaly
• $value: Anomalous value
• $detectors: List of detecting methods
• $tags: Tag values
• $timestamp: Anomaly timestamp

Detector configuration reference

For detailed detector parameters and options, see the ADTK documentation.

Report an issue

For plugin issues, see the Plugins repository issues page.

Find support for InfluxDB 3 Enterprise

The InfluxDB Discord server is the best place to find support for InfluxDB 3 Enterprise. For other InfluxDB versions, see the Support and feedback options.