mcpField
V
vmanomaly-query

vmanomaly-query

github.com/victoriametrics云与 DevOps5984 次安装2 周前更新
代码仓库

关于 vmanomaly-query

通过明确的 API 请求操作运行中的 vmanomaly v1.30+ 实例，适用于管理和排查该服务的人员。它依据实时模式与服务端响应检查、验证、调优和测试配置，并区分验证与实际部署。

主要功能

  1. 01检查健康状态、构建信息和兼容性
  2. 02发现模型与配置模式
  3. 03验证模型和完整配置
  4. 04分析查询并运行调优任务
  5. 05检查服务状态与检测限额

适用场景

  1. 01升级前检查状态兼容性
  2. 02部署前验证配置
  3. 03针对查询执行有界异常检测

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/victoriametrics/skills --skill vmanomaly-query

安装后在 Claude Code 中输入/vmanomaly-query确认已加载。

附带文件references/api-reference.md

详细介绍

vmanomaly API

通过范围明确、调用受限的 API 调用操作运行中的 vmanomaly v1.30+ 实例。优先采用实时 schema 和服务端响应，而非静态假设。

环境与身份验证

# 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 的自定义多对一模型必须声明 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 视为权威信息源。除非目标 schema 明确提供相应参数，否则不要在不同模型类之间沿用参数。

运行前先验证

验证单个模型：

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，请缩短时间间隔或使用更粗的步长。

运行共享自动调优

首先根据配置文件、业务意图、/api/v1/models 和架构选择 tuned_class_name。共享 v1.30 自动调优不会选择模型类。

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 .

创建任务前，告知用户试验次数／时间预算。按顺序轮询一个任务：

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 替换这个具体的一次性建议；可部署的自动包装器有不同的生命周期。此结果中的业务策略仍是模型规格字段，用于兼容任务／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 获取示例配置，使用 /api/vmanomaly/example-alert-rule.yaml 获取 VMAlert 规则。使用 --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，以限制数据源并发数，并在提供配置前验证完整配置。

可选的配套技能

  • 如果可用，使用 victoriametrics-query 在构建 PromQL/MetricsQL 前发现指标名称、标签、基数或现有告警／规则查询。
  • 如果数据源是 VictoriaLogs 且需要通过 LogsQL 进行发现，使用 victorialogs-query。
  • 使用 alertmanager-query 检查活动告警，或避免重复已有的告警意图。

这些都是可选增强功能。如果未安装，请继续使用 vmanomaly 服务／代理端点。

参考

阅读 references/api-reference.md，了解端点参数、响应字段、错误处理和 v1.30 任务语义。

调查触发中的告警

对于 v1.30.7+ 事件链接，在建议启动新的检测任务前，先检查所提供绝对时间窗口内的持久化输出。请遵循事件 API 参考；在声称这些端点支持 MCP 前，先发现可用工具。

评论

支持 Markdown