vmanomaly-review

vmanomaly 配置审查器

在不修改配置的情况下，审查正在运行或拟议中的 vmanomaly v1.30+ 配置。将事实、测量证据和假设分开。静态规则可能比 ML 模型更合适。

判断检测效果或模型与数据的适配性之前，请先阅读 references/evaluation-guide.md。

环境

export VM_ANOMALY_URL="https://vmanomaly.example.com"
# Use /dev/null without authentication. For authenticated instances, point this to a mode-0600
# curl config containing: header = "Authorization: Bearer <token>"
export VM_CURL_CONFIG="${VM_CURL_CONFIG:-/dev/null}"

在基础 URL 中包含任何路径前缀。切勿打印或创建凭据文件。

工作流

1. 加载并总结配置

读取用户提供的 YAML 路径，包括嵌入 Kubernetes 资源中的 configRawYaml。总结：

• 查询别名和表达式；
• 模型别名／类、参数、查询和调度器；
• 调度器的 infer_every、fit_every 和 fit_window；
• 数据源类型和相关读取器设置；
• 已知的预期响应时间和异常检测意图。

按模型对查询分组，以便清楚展示共用参数和多变量关系。缺少查询时，请索要确切查询；不要自行编造。

2. 执行兼容性和功能预检

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/health" | jq .
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/server/buildinfo" | jq .
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/compatibility" | jq .

报告不兼容项和限定范围的清理操作；不要执行清理。没有存储状态属于健康状态。审查升级时使用 ?version_to=X.Y.Z。兼容性涵盖 vmanomaly 管理的状态、受支持的读取器和内置模型，不涵盖自定义模型代码、依赖项或状态；升级到 v1.30.3+ 之前，依赖 is_multivariate = True 的自定义多对一模型必须声明 topology = ModelTopology.MANY_TO_ONE。v1.30 中仅支持 GET。

对于已部署实例，还要确认正在采集自监控指标，并确认官方仪表板和告警规则覆盖服务健康状况、调度器运行状态／重启、重新加载失败、模型错误／跳过、I/O 故障和资源压力。仅有成功的 /health 响应不足以证明生产环境运行状况。

发现运行时别名，并获取每个已配置类的架构：

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/models" | jq .
curl -q --config "$VM_CURL_CONFIG" -sG \
  --data-urlencode 'model_class=<alias>' \
  "$VM_ANOMALY_URL/api/v1/model/schema" | jq .

3. 执行静态验证

验证完整 YAML：

CONFIG_PATH='<user-supplied-yaml-path>'
curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/yaml' --data-binary "@$CONFIG_PATH" \
  "$VM_ANOMALY_URL/api/v1/config/validate" | jq .

另请检查：

• 每个查询／模型／调度器引用均可解析，且没有重要组件成为孤立项；
• 每个模型参数都存在于该精确类的架构中；读取器、调度器、写入器和顶层字段需使用完整配置验证；
• infer_every 满足用户的响应时间要求；
• 拟合历史数据涵盖已配置的日历周期；
• 已知数据范围和显著性阈值与查询单位一致；
• min_n_samples_seen 能在可用历史数据范围内达到要求；
• 多变量 groupby 和通道数量符合预期的依赖分组；
• 请求的 provide_series 不会意外扩大输出基数；
• 离线模型具有合适的重新拟合频率。
• 对于 v1.30.2+ 部署 YAML，稳定的 data_range、detection_direction、min_dev_from_expected 和 min_rel_dev_from_expected 策略属于查询级配置。将模型级配置报告为已弃用但兼容的后备方案，而不是验证失败；显式查询值优先。
• reader.workers 限制数据源并发数，而 settings.n_workers 控制模型进程数，settings.native_threads_per_worker 限制每个进程的原生线程数。

更改类时，必须依据新架构重建规范，而不是逐个删除错误直到验证通过。

4. 重新评估每个信号

标记适合使用更清晰的静态告警的指标：硬性限制、过期、二元状态、单调填充或接近零的故障。避免用可解释性较差的模型重复覆盖精确的静态告警。

对于自然波动、各序列基线不同、趋势／日历行为、持续偏移或跨序列依赖异常，保留 ML。

5. 为每条精确查询生成画像

使用配置的查询步长和时区，并选择足够长的历史窗口以涵盖声称的季节性：

QUERY='<exact-query>'
TIMEZONE='<configured-IANA-timezone>'
curl -q --config "$VM_CURL_CONFIG" -sG \
  --data-urlencode "query=$QUERY" \
  --data-urlencode 'start=<unix-seconds>' \
  --data-urlencode 'end=<unix-seconds>' \
  --data-urlencode 'step=<configured-step>' \
  --data-urlencode "timezone=$TIMEZONE" \
  --data-urlencode 'limit=100' \
  "$VM_ANOMALY_URL/api/v1/timeseries/characteristics" | jq .

将测得的趋势、画像形态、季节性、符合条件的占比、覆盖率和序列数量与配置的类别和画像进行比较。有限结果只是样本。不要据此推算总体的精确数量。

模型拟合预期：

• 存在显著的趋势／日历／节假日／班次画像，或不确定简单平稳基线是否合适：优先使用 temporal_envelope 进行初步检查；
• 已确认画像简单、非季节性，且具有重尾或受离群值污染：使用 mad_online；
• 已确认画像简单、稳定且尾部较轻：使用 zscore_online；
• 依赖关系异常：使用 temporal_envelope_multivariate。

不要推荐离线模型作为备用方案。评估离线模型时，应将其视为旧版选择或用户明确要求的选择，并与相应的在线模型进行比较。

6. 使用有界任务复现

检查容量，然后创建一个使用精确验证模型规范的有界任务：

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/anomaly_detection/limits" | jq .

MODEL_SPEC_JSON='<validated-model-json>'
DATASOURCE_URL='<configured-or-explicit-datasource-url>'
STEP='<configured-step>'
FIT_WINDOW='<configured-fit-window>'
FIT_EVERY='<exploratory-fit-cadence>'
START_INFER_S='<unix-seconds>'
END_INFER_S='<unix-seconds>'
jq -n \
  --arg query "$QUERY" \
  --arg datasource_url "$DATASOURCE_URL" \
  --arg step "$STEP" \
  --arg fit_window "$FIT_WINDOW" \
  --arg fit_every "$FIT_EVERY" \
  --argjson start_infer_s "$START_INFER_S" \
  --argjson end_infer_s "$END_INFER_S" \
  --argjson model "$MODEL_SPEC_JSON" '{
    query:$query,
    datasource_url:$datasource_url,
    step:$step,
    fit_window:$fit_window,
    fit_every:$fit_every,
    start_infer_s:$start_infer_s,
    end_infer_s:$end_infer_s,
    exact:true,
    model_spec:$model
  }' | curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' --data-binary @- \
  "$VM_ANOMALY_URL/api/v1/anomaly_detection/tasks" | jq .

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/anomaly_detection/tasks/<task_id>" | jq .

按顺序轮询，直至状态变为 done、error 或 canceled。评估在线模型的因果效果时使用 exact:true。确保查询步长、时区、方向、数据范围和显著性阈值与生产环境一致。

对于探索性在线任务，将 fit_every 设置为长于推理范围，可保持单一连续状态。这并不意味着它自动就是合适的生产周期。

任务运行期间不要创建重复任务。创建任务和验证配置不会更改部署；应用更改则会。

7. 正确评估证据

没有标签或用户确认事件时：

• 报告检测率，绝不要声称这是误报率；
• 检查不同时段和标签集中的代表性检测结果；
• 询问用户哪些结果有用、属于预期事件或只是噪声；
• 分别检查冷启动、季节性边界、数据缺失和状态转换。

有标签时，应酌情报告精确率、召回率、F1、检测延迟和平稳状态下的误报。在线模型优先采用前向／因果验证。

8. 验证拟议修复

只更改有充分理由需要调整的最小集合，验证后，在相同的有界时间段内重新运行。比较：

• 有用的检测结果和漏掉的已确认事件；
• 检测率或有标签数据的精确率／召回率；
• 在支持的情况下，预测／边界行为；
• 预热和适应延迟；
• 计算、状态和输出基数的影响。

常见修复包括：移除缺乏依据的季节性画像、放宽／收窄常规包络、固定方向／领域阈值、延长拟合历史、拆分异构查询、添加多变量分组，或选择更简单／静态的检测器。

选择模型类别后，共享自动调优可能会生成候选方案。对于在线模型，使用 exact:true 并应用返回的具体 modelConfig；不要悄悄将其转换为 class: auto。

9. 报告

针对每条查询／模型提供：

• 结论：通过、需要更改，或替换为静态规则；
• 来自架构、兼容性、画像和有界测试的证据；
• 严重程度和运行影响；
• 最小拟议更改及更改前后的结果；
• 假设、置信度和后续观察窗口。

将已确认的问题与假设分开。视觉上异常的点不一定是异常，而查询结果为空也不一定能证明数据缺失。

可选配套技能

• victoriametrics-query：验证 PromQL/MetricsQL、自监控数据摄取、标签、基数以及已加载的 vmanomaly 告警规则。
• victorialogs-query：验证 LogsQL 并关联日志行为。
• alertmanager-query：在判定服务健康状态或意图重复之前，检查处于活动、静默或被抑制状态的 vmanomaly 告警。
• investigating-with-observability：将已确认的检测时间窗口与日志/追踪信息关联起来。
• 基数分析技能：评估过多的序列/输出扇出。

这些集成有助于完善证据，但并非必需；如果没有这些集成，请继续使用 vmanomaly 代理和服务端点。

安全

• 未经明确批准，不得应用配置、创建持久规则、清除状态或取消其他用户的任务。
• 限定时间窗口、序列数量上限和任务并发数。
• 在报告中保留确切的查询、时间戳和错误，但应隐去凭据。

事件链接

在 v1.30.7 及更高版本中，vmalert 调查链接会打开已持久化的结果，而不是重新拟合模型。保留发出的别名和绝对时间窗口，使用已配置的分片，并检查当前配置。请参阅事件 API 限制；切勿将标签筛选条件视为访问控制。