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. 範囲を限定したタスクで再現する

容量を確認してから、検証済みの正確なモデル仕様を使用して、範囲を限定したタスクを1つ作成します。

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 の制約を参照してください。ラベルフィルターをアクセス制御として扱わないでください。