vmanomaly-query

vmanomaly API

範囲を限定した明示的な API 呼び出しを通じて、実行中の vmanomaly v1.30+ インスタンスを操作します。静的な前提よりも、実行時のスキーマとサーバーの応答を優先してください。

環境と認証

# Include any configured path prefix in the base URL.
export VM_ANOMALY_URL="https://vmanomaly.example.com"
# Use /dev/null for unauthenticated local instances. 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}"

認証情報をプロセス引数に含めず、すべてのリクエストで同じ設定を使用してください。

curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/health" | jq .

認証情報ファイルを表示したり作成したりしないでください。VM_ANOMALY_URL が未設定の場合は、ユーザーに尋ねてください。

実行時の事前確認から始める

設定、レビュー、自動チューニング、または移行の作業を行う前に、次のチェックを実行してください。

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 .

互換性は慎重に解釈してください。

• global_check.has_state=false：移行が必要な永続状態はありません。
• global_check.is_compatible=true：対象範囲内の vmanomaly 管理下の状態は再利用できます。
• global_check.drop_everything=true：永続状態をすべて削除する必要があることを報告してください。自動で削除しないでください。
• component_assessment.models_to_purge または should_purge_reader_data：対象範囲が限定されたクリーンアップを報告してください。
• ?version_to=X.Y.Z を使用すると、保存済みの状態を計画中のターゲットリリースと照合して評価できます。

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

実装されているのは GET による互換性チェックのみです。任意の設定を受け付ける POST エンドポイントを作り出さないでください。設定の構文を確認するには、代わりに /api/v1/config/validate を使用してください。

使用前に機能を確認する

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 .

/api/v1/models と /api/v1/model/schema を信頼できる情報源として扱ってください。対象のスキーマで公開されていない限り、モデルクラス間でパラメーターを引き継がないでください。

実行前に検証する

1 つのモデルを検証します。

curl -q --config "$VM_CURL_CONFIG" -s \
  -X POST -H 'Content-Type: application/json' \
  -d '{"class":"temporal_envelope","seasonalities":["hod_smooth","dow_smooth"]}' \
  "$VM_ANOMALY_URL/api/v1/model/validate" | jq .

設定全体を検証します。

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 .

検証によって設定が適用または再読み込みされることはありません。

実行中のサーバーを調べる

# Configured query aliases and expressions.
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/server/queries" | jq .

# Configured datasource context. Keep only documented fields and redact URL user information.
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/api/v1/server/datasource" | jq '
    with_entries(select(.key | IN("server_datasource_url", "ui_datasource_url", "ui_datasource_type")))
    | with_entries(
        if (.value | type) == "string" and (.key | endswith("_url"))
        then .value |= sub("://[^/@]+@"; "://<redacted>@")
        else .
        end
      )'

# Prometheus-format self-monitoring metrics.
curl -q --config "$VM_CURL_CONFIG" -s \
  "$VM_ANOMALY_URL/metrics?name[]=vmanomaly_scheduler_alive&name[]=vmanomaly_scheduler_restarts_total&name[]=vmanomaly_model_run_errors&name[]=vmanomaly_model_runs_skipped"

/health は特定時点での事前確認として扱い、本番環境の監視には使用しないでください。実行中のデプロイでは、文書化されているセルフモニタリングメトリクスをスクレイピングまたはプッシュすること、Grafana ダッシュボードをインストールすること、提供されているアラートルールを確認することを推奨してください。サービスの可用性、スケジューラーの稼働状況と再起動、再読み込みの失敗、モデルのエラーとスキップ、I/O エラー率、リソースの逼迫を優先してください。ユーザーの承認なしに、ルールやダッシュボードをデプロイしないでください。

インストールされている場合は、victoriametrics-query を使用してセルフモニタリング系列が取り込まれていることと、想定されるルールが読み込まれていることを確認してください。alertmanager-query を使用して、vmanomaly のアクティブ、一時停止中、または抑制中のアラートを調べてください。

モデルを選ぶ前にクエリのプロファイルを取得する

空でない正確なクエリが必要です。ユーザーがクエリを指定している場合は、それを再利用してください。指定されていない場合は、設定済みのクエリエイリアスを解決するか、ユーザーに尋ねてください。メトリクスの説明から本番用クエリを決して作り出さないでください。

QUERY='sum(rate(http_requests_total{job="api"}[5m])) by (service)'
TIMEZONE='America/New_York'
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 .

プロファイル取得、自動チューニング、最終的なタスク／設定で、同じ step を使用してください。件数が制限された応答は、母集団全体の正確な要約ではなく、サンプルとして扱ってください。件数制限付きの読み取りでチャンク分割に関する 422 が返された場合は、期間を短くするか、step を粗くしてください。

共有 autotune の実行

プロファイル、ビジネス上の意図、/api/v1/models、およびスキーマから、まず tuned_class_name を選択します。共有 v1.30 autotune ではモデルクラスを選択しません。

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 .

タスクを作成する前に、試行回数／時間の予算をユーザーに伝えます。タスクを1つずつ順番にポーリングします。

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

done、error、canceled を終端状態として扱います。done になったら、result_data.data.modelConfig をそのまま適用し、検証してテストします。この具体的な一度限りの推奨設定を class: auto に置き換えないでください。デプロイ可能な auto ラッパーはライフサイクルが異なります。この結果に含まれるビジネスポリシーは、タスク／UI との互換性のため、引き続きモデル仕様のフィールドとして扱います。v1.30.2 以降のデプロイ設定を作成する場合に限り、これらを関連付けられたクエリに移動します。ユーザーがキャンセルを求めた場合に限り DELETE を使用します。

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

上限付き検出タスクの実行

まず容量を確認します。

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

model_spec を検証してからタスクを作成します。v1.30.3 のタスク契約では datasource_url の明示が必須です。適切な場合は、設定済みのデータソース URL を再利用します。

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

因果的なオンラインモデル評価には exact:true を使用します。順番にポーリングし、タスクが実行中であるという理由だけで重複タスクを作成しないでください。

デプロイ用アーティファクトの生成

設定例には /api/vmanomaly/config.yaml を、VMAlert ルールには /api/vmanomaly/example-alert-rule.yaml を使用します。値は --data-urlencode で渡します。設定エンドポイントは、互換性を重視したモデルレベルのビジネスフィールドを保持します。v1.30.2 以降のデプロイ YAML では、data_range、detection_direction、min_dev_from_expected、min_rel_dev_from_expected を reader.queries.<alias> に移動し、データソースの同時実行数を制限するために reader.workers: 0 を検討したうえで、提示する前に完成した設定全体を検証します。

任意の補助スキル

• PromQL／MetricsQL を構築する前に、利用可能であれば victoriametrics-query を使用して、メトリクス名、ラベル、カーディナリティ、既存のアラート／ルールクエリを確認します。
• データソースが VictoriaLogs で、LogsQL の調査が必要な場合は victorialogs-query を使用します。
• アクティブなアラートを確認したり、既存のアラート意図との重複を避けたりするには alertmanager-query を使用します。

これらは任意の拡張機能です。インストールされていない場合も、vmanomaly のサーバー／プロキシエンドポイントを利用して作業を続けてください。

リファレンス

エンドポイントのパラメーター、レスポンスフィールド、エラー処理、v1.30 のタスクの動作については、references/api-reference.md を参照してください。

発報中のアラートの調査

v1.30.7 以降のインシデントリンクについては、新たな検出実行を提案する前に、指定された絶対時刻の範囲内にある永続化済みの出力を調査します。インシデント API リファレンスに従ってください。これらのエンドポイントが MCP に対応していると主張する前に、利用可能なツールを確認してください。