vmanomaly-config

vmanomaly 設定ビルダー

既知の監視目的を、検証済みの vmanomaly v1.30+ 設定に変換します。ML の運用コストに見合う価値があるかを確認するため、まず静的ルールで障害条件をより明確に表現できるかを判断してください。

モデルまたはそのパラメーターを選択する前に、references/model-selection.md を読んでください。継続的に実行するデプロイを作成する場合は、references/deployment-readiness.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}"

設定済みのパスプレフィックスがある場合は、VM_ANOMALY_URL に含めてください。認証情報ファイルを表示したり、作成したりしないでください。URL が不明な場合は、ユーザーに確認してください。

ワークフロー

1. 目的を確認し、正確なクエリを取得する

以下を収集または推定してください。

• 正確な PromQL/MetricsQL または LogsQL 式
• 検出するスパイク、低下、レベルシフト、季節性の崩れ、またはトレンドの崩れ
• 方向：above_expected、below_expected、または両方
• 希望する反応時間とクエリのステップ
• 本番クエリとカレンダープロファイルで使用する IANA タイムゾーン
• 既知の物理的な上限・下限、および重要でない絶対値／相対値の偏差
• 感度の希望と、許容可能な上限検知率

モデルのクエリフィールドが空でも、ユーザーがすでにクエリを提示している場合は、それをプロファイリングに使用し、UI のクエリ入力欄に設定するよう推奨してください。クエリが存在しない場合は、ユーザーに確認してください。メトリックの説明から本番クエリを作り出してはいけません。

インストールされている場合、victoriametrics-query または victorialogs-query を使って、名前、ラベル、有効な式を調べることができます。これらがなくても、このスキルを中断してはいけません。

2. 静的アラートと ML を選別する

明確な異常値がある場合は、静的な VMAlert ルールを優先してください。

シグナルの形状	最初に選ぶべき方法
ほぼゼロのエラー数／再起動数	> threshold for duration
単調に増加する容量の使用量	predict_linear とパーセンテージのしきい値
バイナリ状態／稼働・停止状態	直接のしきい値、absent()、または changes()
有効期限または厳格な安全上限	直接のしきい値

正常な値が時刻、インスタンス、ワークロード、または変動するベースラインによって変化する場合、日次、週次、月次、祝日のパターンが重要な場合、または複数系列間の関係がシグナルである場合は、vmanomaly を使用してください。autotune の予算を使う前に、この判断を提示してください。

3. ランタイムの事前確認を実行する

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 .

互換性レスポンスはクリーンアップ処理ではなく、事前確認として扱ってください。

• 保存された状態がない場合は正常です。
• drop_everything、削除対象のモデル、またはリーダーデータのクリーンアップについて報告してください。
• ユーザーの明示的な承認なしに、状態を削除してはいけません。
• アップグレードを計画している場合は、?version_to=X.Y.Z を使用してください。

互換性の確認対象は、vmanomaly が管理する状態、サポート対象のリーダー、組み込みモデルです。カスタムモデルのコード、依存関係、または状態は対象外です。v1.30.3+ にアップグレードする前に、is_multivariate = True に依存するカスタムの many-to-one モデルでは、topology = ModelTopology.MANY_TO_ONE を宣言する必要があります。

v1.30 で利用できるのは GET による互換性チェックのみです。

4. 実データをプロファイリングする

最終的なタスク／設定で使用するものと同じ step を使用してください。

QUERY='<exact-query>'
TIMEZONE='<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=5m' \
  --data-urlencode "timezone=$TIMEZONE" \
  --data-urlencode 'limit=100' \
  "$VM_ANOMALY_URL/api/v1/timeseries/characteristics" | jq .

メトリック名から推測するのではなく、実測されたトレンド、日次／週次／月次プロファイル、形状、適格性、カバレッジを使用してください。件数制限付きの結果はサンプルです。件数制限付きの読み取りでチャンク分割に関する 422 が返された場合は、期間を短くするか、より粗いステップを使用してください。

5. 対応モデルを確認して選択する

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=temporal_envelope' \
  "$VM_ANOMALY_URL/api/v1/model/schema" | jq .

ライブのエイリアス一覧とスキーマを信頼できる情報源として使用してください。クラスを変更する場合はモデル仕様を作り直し、古いパラメーターを別のクラスに持ち越さないでください。

デフォルトの優先順位：

1. トレンド、カレンダーパターン、祝日、持続的な変化、予測、不確実性、または単純な定常ベースラインで十分かどうか判断できない場合など、単純ではない時間的プロファイルには temporal_envelope を使用してください。
2. プロファイリングによって、データが単純で非季節性かつ比較的安定していると確認できた場合に限り、mad_online または zscore_online を使用してください。歪みがある、裾が重い、または外れ値が混入したデータには MAD を優先してください。分布が安定していて裾が軽く、標準偏差による大きさに意味がある場合に限り、Z-score を使用してください。
3. チャネル間の関係自体が異常となる、整列されたチャネルには temporal_envelope_multivariate を使用してください。
4. 通常の推奨フローではオフラインモデルを導入しないでください。レガシー設定を確認する場合、ユーザーが明示的に求めた場合、またはオンラインモデルでは得られない実質的な利点が管理された比較で確認されている場合に限り、オフラインモデルについて説明してください。

6. ドメイン知識を公開コントロールに反映する

• ビジネス上の意図が明らかな場合は detection_direction を固定し、重要でない絶対偏差／相対偏差を min_dev_from_expected と min_rel_dev_from_expected に割り当ててください。
• v1.30.2 以降のデプロイ可能な YAML では、data_range、detection_direction、min_dev_from_expected、min_rel_dev_from_expected を reader.queries.<alias> の下に配置してください。クエリの値は、関連付けられたモデル全体で優先されます。モデルレベルの値はローカルなフォールバックとして引き続き使用できますが、非推奨です。
• VMUI では、接続されている提案コントラクトを確認してください。suggest_query_config が queries と expected_revision を公開している場合は、エイリアス、有効状態、クエリごとのポリシーを含む名前付きクエリ行をすべて適用し、現在のリビジョンをコピーして、変更しない行を保持してください。null／省略されたポリシーは継承されます。明示的なゼロ、both、unbounded の値は上書き値として扱われます。古い単一クエリのコントラクトでは、名前付きクエリセットを適用できません。そのポリシーを黙って削除しないでください。モデルレベルのデフォルトは分けて保持してください。
• 予測と区間の出力をそのドメインにクリップする必要がある場合に限り、モデルレベルの clip_predictions を設定してください。
• コールドスタート中のスコアを抑制するには min_n_samples_seen を使用してください。その期間は、サンプル数にクエリのステップを乗じて表してください。
• 安定した MAD、Z-score、またはオンライン分位点データでは、追加の学習サイクルを多く実行する代わりに history_strength > 1 を検討してください。必要な季節位相をすべてカバーできるだけの履歴を確保してください。
• プロファイルでサポートされているカレンダープリセットだけを選択してください。Temporal Envelope のプロファイルはタイムゾーンと DST に対応しています。プロファイリングで使用したものと同じ IANA タイムゾーンを reader.queries.<alias>.tz（またはリーダーレベルの tz）に設定してください。
• ユーザーが将来の状態の予測またはキャパシティプランニングを必要としない限り、forecast_at は空のままにしてください。
• オートチューニング中は、多変量の groupby、祝日、その他のドメイン構造を固定してください。

7. 直接設定と共有オートチューニングを選択する

直接設定では、スキーマのデフォルトから始め、根拠のあるコントロールのみを変更してください。

共有オートチューニングでは、まずモデルクラスを選択してください。試行数／時間の予算を示してから、範囲を限定したタスクを1つ作成してください。オンラインモデルでは、因果的で厳密な検証を使用してください。

jq -n --arg query "$QUERY" --arg timezone "$TIMEZONE" '{
    query:$query,
    "tuned_class_name":"temporal_envelope",
    "anomaly_percentage":0.02,
    "start":1710000000,
    "end":1711209600,
    "step":"5m",
    timezone:$timezone,
    "limit":100,
    "use_profile_hints":true,
    "optimization_params":{"n_trials":64,"timeout":30,"exact":true,"optimize_complexity":true},
    "frozen_params":{"detection_direction":"above_expected"}
  }' | curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' --data-binary @- \
  "$VM_ANOMALY_URL/api/v1/autotune/tasks" | jq .

GET /api/v1/autotune/tasks/{task_id} を順番にポーリングしてください。成功したら、具体的な result_data.data.modelConfig を使用し、検証してテストしてください。class: auto に置き換えないでください。このラッパーはフィットごとに再チューニングを行うもので、明示的に選択する別個のライフサイクルです。オートチューニングでもモデル仕様は返されます。VMUI／アドホックテストでは固定したビジネスフィールドをそのまま保持してください。ただし、v1.30.2 以降のデプロイ用 YAML を組み立てる際は、対応するクエリに移してください。

8. 検証とテスト

モデル仕様を検証します。

curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' \
  -d @model.json "$VM_ANOMALY_URL/api/v1/model/validate" | jq .

YAML 全体を適用せずに検証します。

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

次に、容量を確認し、検証済みモデルを使って範囲を限定した検出タスクを実行します。v1.30.3 のタスク契約では datasource_url の明示が必要です。適切な場合は、設定済みのデータソース URL を再利用します。

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

DATASOURCE_URL='<configured-or-explicit-datasource-url>'
jq -n --arg query "$QUERY" --arg datasource_url "$DATASOURCE_URL" --slurpfile model model.json '{
    query:$query,
    datasource_url:$datasource_url,
    step:"5m",
    fit_window:"30d",
    fit_every:"1000w",
    start_infer_s:1710000000,
    end_infer_s:1710086400,
    exact:true,
    model_spec:$model[0]
  }' | 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 .

返されたタスク ID を順番にポーリングし、done、error、または canceled になるまで続けます。オンラインモデルでは exact:true を使用し、推論中に初期フィットが因果的に進化するよう、fit_every: 1000w のように再フィットを事実上無効にする設定をデフォルトとします。定期的な再フィットは、明示的に必要な場合にのみ設定します。

検出結果を目視で確認し、既知のイベントと照合して評価します。正解ラベルがない場合、観測された割合は偽陽性率ではなく検出率と呼びます。モデルを厳しく調整する前に、どの検出が有用だったかをユーザーに尋ねます。

9. デプロイ可能な成果物を提供する

以下を提供します。

• 静的ルールまたは完全な vmanomaly YAML。
• 生成された異常スコア用の VMAlert ルール。
• プロファイルのエビデンスとビジネス上の目的に基づく根拠。
• クエリのステップ、フィット期間／頻度、ウォームアップ、想定反応時間、リソースに関する注意事項。
• 検証／テスト結果と、本番環境での確認が必要な前提条件。
• セルフモニタリングの統合。ポイントインタイムのヘルスチェックに頼るのではなく、本番環境では公式ダッシュボードとアラートルールを推奨します。
• references/deployment-readiness.md に基づき、根拠を示した状態の復元、保持期間、ホットリロード、永続化、ワークロード分散の選択。

生成された /api/vmanomaly/config.yaml と /api/vmanomaly/example-alert-rule.yaml の出力は出発点であり、正しさを保証するものではありません。設定エンドポイントは VMUI／モデル仕様との互換性を保つ形式を維持します。v1.30.2 以降のデプロイ用 YAML を提示する前に、安定した 4 つのビジネスポリシーを reader.queries.<alias> に移し、適切な場合は reader.workers を追加して、最終設定を検証してください。

Copilot のコンテキストを効率的に使う

すでに利用可能なスキーマ、プロファイル、完了済みタスクの結果を再利用します。検索対象を絞ったドキュメント検索では、上限件数を少数（通常は 3～5 件）に明示的に設定します。検索結果は抜粋の場合があります。参照元の URI、オフセット、省略を示すマーカーを確認し、内容を信頼する前に、不足しているコンテキストを vmanomaly_read_doc_section で取得してください。抜粋に記載がないことを、パラメーターや制約が存在しない証拠として扱わないでください。広範な検索や、会話履歴へのドキュメント全文の繰り返し追加は避けてください。

提案する設定は、承認カードを通じて一度だけ提示し、独立した YAML の提示は明示的なエクスポート依頼があった場合に限ります。説明は簡潔にします。クエリエイリアス、式、無効化された行、ビジネスポリシーの継承、検証制約、承認待ちのデータを削除してコンテキストを節約してはいけません。名前付きクエリの UI への適用は、共有の名前付きクエリオートチューンに対応していることを意味しません。実際のツールスキーマを確認してください。

バックエンドは、重複する完了済みツール結果を圧縮する場合があり、プロバイダーとは独立してローカルのコンテキスト予算を適用することがあります。予算超過で拒否された場合は、現在の UI 状態を維持し、より範囲を絞った依頼または新しい会話で再開する方法を説明します。適用されていない提案が成功したと主張してはいけません。トークン上限は出力の最大許容量であり、目標ではありません。使用量カウンターやバイト数の比較は測定に役立ちますが、プロバイダーへの請求額が正確に削減されたことを証明するものではありません。

名前付きクエリの同時オートチューニング

接続先のオートチューニングスキーマで queries が公開されている場合は、有効なエイリアスと正確な式を対応付けたマップを1つ送信し、明示的なビジネスポリシーを指定して、レガシーの query フィールドは省略します。null／省略による継承と、明示的なゼロ、両方、および上限なしの上書きを区別してください。実際の多変量モデルクラスを1つのタスクでチューニングし、モデルのグループ化は frozen_params.groupby に設定します。各候補は、独立してフィッティングされた整列済みグループ全体で評価され、共有設定が1つ生成されます。個別にチューニングした単変量の設定をマージして、その結果を同時チューニング済みの多変量検出として説明してはいけません。クエリごとの式のサンプル上限を引き上げ、すべてのクエリに一致するグループを含める必要がある場合があります。グループが不完全な場合は、明示的に失敗します。

この仕様に対応していない古いサーバーでは、クエリやそのポリシーを黙って破棄せず、制限事項を説明してください。anomaly_percentage はチューニング目標として説明し、異常や誤検知の上限が保証されるものとして説明しないでください。既存の名前付きクエリとポリシーの状態を維持したまま、得られたモデルの提案を適用してください。クエリ単位のポリシーを誤って共有デフォルトに昇格させないでください。

安全性

• API の検証やタスクによって、設定がデプロイされたり、ホットリロードされたりすることはありません。
• 設定の適用、永続的なアラートルールの作成、または状態の削除を行う前に、承認を得てください。
• サンプル数、時間範囲、系列数の上限、試行回数、同時実行タスク数に上限を設定してください。
• クエリとラベルを確認するまでは、データが空であることを理由に、そのメトリックが存在しないと推測しないでください。

UI のモデル選択肢

vmanomaly v1.30.7 以降で利用できます。

server.ui_allowed_models は、手動のモデルセレクターと Auto の対象のみを絞り込みます。Copilot、設定済みモデル、共有リンク、API 実行は制限されません。この設定を認可境界として使用しないでください。