name: victoriametrics-metrics description: 使用 MetricsQL 进行 VictoriaMetrics 指标分析。用于查询存储在 VictoriaMetrics 中的时间序列指标。支持 PromQL 和 MetricsQL 扩展。 allowed-tools: Bash(python *)

VictoriaMetrics 指标分析

使用 MetricsQL（兼容 PromQL 并带扩展）查询和分析来自 VictoriaMetrics 的时间序列指标。

认证

重要：凭证由代理层自动注入。请勿检查环境变量中的 VICTORIAMETRICS_TOKEN — 它们对您不可见。直接运行脚本；认证透明处理。

强制要求：上下文高效调查

切勿转储所有序列或运行无限制范围查询。 始终遵循此模式：

获取统计 → 即时查询 → 范围查询（仅在需要时）

统计优先 — 了解存在多少序列，哪些指标/作业活跃
即时查询 — 获取当前值（单点，紧凑输出）
范围查询 — 仅在需要时间趋势时使用，并始终使用 topk() 限制输出

可用脚本

所有脚本位于 .claude/skills/metrics-victoriametrics/scripts/

get_statistics.py — 始终从此开始

发现存在的指标及其基数。

python .claude/skills/metrics-victoriametrics/scripts/get_statistics.py --query '{job="api"}'
python .claude/skills/metrics-victoriametrics/scripts/get_statistics.py --query '{namespace="production"}' --time-range 120
python .claude/skills/metrics-victoriametrics/scripts/get_statistics.py --query '{}' --json

输出包括：

活跃序列计数
按序列计数排名的前10个指标名称
前5个作业
紧凑摘要（约20行）

query_metrics.py — 定向查询

执行 MetricsQL 查询并限制输出。

# 即时查询（默认 - 每个序列单值，紧凑）
python .claude/skills/metrics-victoriametrics/scripts/query_metrics.py --query 'up{job="api"}'
python .claude/skills/metrics-victoriametrics/scripts/query_metrics.py --query 'rate(http_requests_total{service="payment"}[5m])'

# 范围查询（谨慎使用 - 显示每个序列的最新值，而非所有数据点）
python .claude/skills/metrics-victoriametrics/scripts/query_metrics.py --query 'rate(http_requests_total[5m])' --type range --time-range 60

# 限制输出
python .claude/skills/metrics-victoriametrics/scripts/query_metrics.py --query 'topk(5, rate(http_requests_total[5m]))' --limit 10 --json

list_labels.py — 元数据发现

发现可用标签和值。

python .claude/skills/metrics-victoriametrics/scripts/list_labels.py
python .claude/skills/metrics-victoriametrics/scripts/list_labels.py --label job
python .claude/skills/metrics-victoriametrics/scripts/list_labels.py --label namespace --match '{job="api"}' --json

MetricsQL 快速参考

MetricsQL 完全兼容 PromQL 并带有额外扩展。

基本查询

# 即时向量
http_requests_total{service="api"}

# 每秒增长率
rate(http_requests_total{service="api"}[5m])

# 直方图分位数
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

聚合

sum by (service) (rate(http_requests_total[5m]))
avg by (instance) (cpu_usage)
topk(5, sum by (service) (rate(http_requests_total[5m])))
bottomk(3, avg_over_time(cpu_usage[1h]))

MetricsQL 扩展（超越 PromQL）

WITH 模板 — 可重用过滤器

WITH (
  commonFilters = {job="api", env="prod"},
  errorRate(m) = rate(m{status=~"5.."}[5m]) / rate(m[5m])
)
errorRate(http_requests_total{commonFilters})

汇总函数

rollup(metric[5m])              # 在一次查询中返回最小值、最大值、平均值
rollup_rate(counter[5m])        # 具有适当计数器重置处理的速率
rollup_increase(counter[5m])    # 具有计数器重置处理的增量

标签操作

label_set(metric, "env", "prod")       # 设置标签值
label_del(metric, "instance")          # 删除标签
label_copy(metric, "pod", "instance")  # 复制标签
label_move(metric, "old", "new")       # 重命名标签
label_join(metric, "dst", ",", "a", "b")  # 连接标签

范围和时间函数

range_median(metric[1h])         # 范围中位数
range_first(metric[1h])         # 范围第一个值
range_last(metric[1h])          # 范围最后一个值
running_avg(metric[1h])         # 运行平均值

标签匹配

{status="500"}           # 精确匹配
{status=~"5.."}          # 正则匹配
{status!="200"}          # 不等于
{service="api", status=~"5.."}   # 多个标签

调查工作流

错误率调查

# 步骤 1：获取统计
python get_statistics.py --query '{job="api"}'

# 步骤 2：当前错误率
python query_metrics.py --query 'sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))'

# 步骤 3：按服务错误率（仅前5）
python query_metrics.py --query 'topk(5, sum by (service) (rate(http_requests_total{status=~"5.."}[5m])))'

延迟调查

python query_metrics.py --query 'histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket{service="api"}[5m])))'

资源调查

python query_metrics.py --query 'topk(5, rate(container_cpu_usage_seconds_total{namespace="prod"}[5m]))'
python query_metrics.py --query 'topk(5, container_memory_usage_bytes{namespace="prod"} / container_spec_memory_limit_bytes{namespace="prod"})'

避免的反模式

切勿运行无限制的 query_range — 始终使用 topk() 或按特定标签过滤
切勿跳过 get_statistics.py — 在查询前了解基数
切勿使用不带范围向量的 rate() — 始终包含 [5m] 或类似
切勿直接比较计数器 — 首先使用 rate() 或 increase()
避免在范围查询中使用短步长 — 使用 step >= 2x 抓取间隔