基于 MAD 的异常检测插件

基于MAD的异常检测插件利用中位数绝对偏差（MAD）为InfluxDB 3中的时间序列数据提供实时异常检测。在数据写入时检测字段值中的异常值，并为基于计数和基于时间的警报设置可配置的阈值。该插件维护内存中的双端队列以进行高效计算，并与通知发送器插件集成，通过多种渠道发送警报。

配置

必需参数

MAD阈值参数

多个阈值用@分隔：temp:2.5:20:5@load:3:10:2m

可选参数

默认通知模板

• 计数："MAD计数警报：字段 $field 在 $table 连续 $threshold_count 个点出现异常。标签：$tags"
• 时间："MAD时间警报：字段 $field 在 $table 异常持续 $threshold_time。标签：$tags"

通知渠道参数

Slack

Discord

HTTP

SMS/WhatsApp (通过Twilio)

架构要求

该插件假定表架构已在数据库中定义，因为它依赖于此架构来检索处理所需的字段和标签名称。

TOML 配置

要使用 TOML 配置文件，请设置 PLUGIN_DIR 环境变量并在触发器参数中指定 config_file_path。 这与启动 InfluxDB 3 时的 --plugin-dir 标志是附加的。

示例 TOML 配置

mad_anomaly_config_data_writes.toml

有关使用 TOML 配置文件，请参阅 influxdb3_plugins /README.md 中的“使用 TOML 配置文件”部分。

安装

1. 启用处理引擎来启动 InfluxDB 3 核心（--plugin-dir /path/to/plugins）

2. 安装必需的 Python 包

   • requests (用于通知传递)

   influxdb3 install package requests

3. 安装并配置官方的Notifier插件

触发器设置

实时异常检测

在数据写入时检测异常

influxdb3 create trigger \
  --database mydb \
  --plugin-filename gh:influxdata/mad_check/mad_check_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments 'measurement=cpu,mad_thresholds="temp:2.5:20:5@load:3:10:2m",senders=slack,slack_webhook_url="https://hooks.slack.com/services/..."' \
  mad_anomaly_detector

示例用法

示例1：基本的基于计数的异常检测

检测温度连续5个点超出中位数2.5倍MAD

# Create trigger for count-based detection
influxdb3 create trigger \
  --database sensors \
  --plugin-filename gh:influxdata/mad_check/mad_check_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments 'measurement=environment,mad_thresholds="temperature:2.5:20:5",senders=slack,slack_webhook_url="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"' \
  temp_anomaly_detector

# Write test data with an anomaly
influxdb3 write \
  --database sensors \
  "environment,room=office temperature=22.1"
influxdb3 write \
  --database sensors \
  "environment,room=office temperature=22.3"
influxdb3 write \
  --database sensors \
  "environment,room=office temperature=45.8"  # Anomaly
# Continue writing anomalous values...

预期结果

• 插件维护最近20个温度值的窗口
• 从该窗口计算中位数和MAD
• 当温度连续5个点超出中位数±2.5*MAD时，发送Slack通知
• 通知包含：“MAD计数警报：字段temperature在environment连续异常5个点。标签：room=office”

示例2：带多个字段的基于时间的异常检测

使用不同的阈值监控CPU负载和内存使用率

# Create trigger with multiple thresholds
influxdb3 create trigger \
  --database monitoring \
  --plugin-filename gh:influxdata/mad_check/mad_check_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments 'measurement=system_metrics,mad_thresholds="cpu_load:3:30:2m@memory_used:2.5:30:5m",senders=slack.discord,slack_webhook_url="https://hooks.slack.com/...",discord_webhook_url="https://discord.com/api/webhooks/..."' \
  system_anomaly_detector

预期结果

• 独立监控两个字段
  • cpu_load：当超过3 MADs持续2分钟时发出警报
  • memory_used：当超过2.5 MADs持续5分钟时发出警报
• 发送通知到Slack和Discord

示例3：带翻转抑制的异常检测

防止由快速波动的数值引起的警报疲劳

# Create trigger with flip suppression
influxdb3 create trigger \
  --database iot \
  --plugin-filename gh:influxdata/mad_check/mad_check_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments 'measurement=sensor_data,mad_thresholds="vibration:2:50:10",state_change_count=3,senders=http,http_webhook_url="https://api.example.com/alerts",notification_count_text="Vibration anomaly detected on $table. Field: $field, Tags: $tags"' \
  vibration_monitor

预期结果

• 检测振动异常，在连续10个点中超出2 MADs
• 如果在50点窗口内，数值在正常/异常状态之间翻转超过3次，则抑制通知
• 发送自定义格式的消息到HTTP端点

使用 TOML 配置文件

此插件支持使用TOML配置文件指定所有插件参数。

重要要求

要使用TOML配置文件，您必须在InfluxDB 3主机环境中设置PLUGIN_DIR环境变量。

设置TOML配置

1. 设置PLUGIN_DIR环境变量后启动InfluxDB 3:

   PLUGIN_DIR=~/.plugins influxdb3 serve --node-id node0 --object-store file --data-dir ~/.influxdb3 --plugin-dir ~/.plugins

2. 将示例TOML配置文件复制到您的插件目录:

   cp mad_anomaly_config_data_writes.toml ~/.plugins/

3. 编辑TOML文件以匹配您的需求

   # Required parameters
   measurement = "cpu"
   mad_thresholds = "temp:2.5:20:5@load:3:10:2m"
   senders = "slack"
   
   # Notification settings
   slack_webhook_url = "https://hooks.slack.com/services/..."
   notification_count_text = "Custom alert: $field anomaly detected"

4. 使用config_file_path参数创建触发器:

   influxdb3 create trigger \
     --database mydb \
     --plugin-filename mad_check_plugin.py \
     --trigger-spec "all_tables" \
     --trigger-arguments config_file_path=mad_anomaly_config_data_writes.toml \
     mad_toml_trigger

代码概述

文件

• mad_check_plugin.py：包含数据写入触发器处理程序的主要插件代码
• mad_anomaly_config_data_writes.toml：示例TOML配置文件

日志记录

日志存储在_internal数据库的system.processing_engine_logs表中

influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'"

日志列

• event_time：日志事件的时间戳
• trigger_name：生成日志的触发器名称
• log_level：严重性级别（INFO、WARN、ERROR）
• log_text：描述操作或错误的邮件

主函数

process_writes(influxdb3_local, table_batches, args)

处理传入数据的实时异常检测。

关键操作

1. 过滤指定度量的表批次
2. 为每个字段维护最近值的内存双端队列
3. 计算每个监控字段的MAD
4. 跟踪连续的异常值和持续时间
5. 在满足阈值时发送通知

关键算法

MAD（中位数绝对偏差）计算

median = statistics.median(values)
mad = statistics.median([abs(x - median) for x in values])
threshold = k * mad
is_anomaly = abs(value - median) > threshold

翻转检测

计算窗口内正常和异常状态之间的转换次数，以防止由快速变化值引起的警报疲劳。

故障排除

常见问题

问题：未发送通知

解决方案:

1. 验证通知发送插件是否已安装并运行
2. 检查Webhook URL是否正确

   influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%notification%'"

3. 确保为选定的发送者提供了通知渠道参数

问题：“MAD阈值格式无效”错误

解决方案：检查阈值格式是否正确

• 基于计数：field:k:window:count (例如，temp:2.5:20:5)
• 基于时间：field:k:window:duration (例如，temp:2.5:20:2m)
• 多个阈值用@分隔

问题：误报过多

解决方案:

1. 增加k乘数（例如，从2.5到3.0）
2. 增加阈值计数或持续时间
3. 使用state_change_count启用翻转抑制
4. 增加窗口大小以获得更稳定的统计数据

问题：遗漏异常（假阴性）

解决方案:

1. 减少k乘数
2. 减少阈值计数或持续时间
3. 检查数据是否具有影响中位数的季节性模式

调试技巧

1. 监控双端队列大小:

   influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%Deque%'"

2. 检查MAD计算:

   influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE log_text LIKE '%MAD:%'"

3. 使用已知异常进行测试：写入具有明显异常值的测试数据以验证检测

性能注意事项

• 内存使用：每个字段维护一个包含window_count值的双端队列
• 计算：每次写入监控字段的数据时都会计算MAD
• 缓存：度量和标签名称缓存1小时
• 通知重试：失败的通知最多重试3次，采用指数退避策略

报告问题

有关插件问题，请参阅插件存储库的 issues 页面。

查找 InfluxDB 3 Core 的支持

加入 InfluxDB Discord 服务器 是获取 InfluxDB 3 Core 和 InfluxDB 3 Enterprise 支持的最佳途径。对于其他 InfluxDB 版本，请参阅 支持和反馈 选项。