victoriametrics-unused-metrics-analysis

查找 VictoriaMetrics 中未使用的指标

找出已写入但从未（或很少）被查询的指标，并提出具体措施，以免浪费存储和写入资源。

环境

使用与 victoriametrics-query 技能相同的环境变量：

# $VM_METRICS_URL - base URL
#   cluster: export VM_METRICS_URL="https://vmselect.example.com/select/0/prometheus"
#   single: export VM_METRICS_URL="http://localhost:8428"
# $VM_CURL_CONFIG - curl config file with auth header (unset if no auth is required)
#   Remote: export VM_CURL_CONFIG="$HOME/.config/victoriametrics/curl.conf"
#   Local:  leave unset (defaults to /dev/null - no auth)

工作原理

VictoriaMetrics 会跟踪每个指标名称在查询中被获取的次数，以及上次被获取的时间。这由 metric_names_stats API 实现，该 API 自 v1.113.0 起提供。通过比较实际写入的数据和实际查询的数据，可以找出无人使用的指标，并安全地将其删除。

工作流程分为三个阶段：

Phase 1: Verify feature is enabled
Phase 2: Collect and analyze usage data
Phase 3: Report findings and suggest fixes

阶段 1：验证功能是否可用

开始前，先检查指标名称统计跟踪器是否返回数据。自 v1.113.0 起，此功能默认启用，但可能已被禁用，或者实例版本过旧。

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?limit=3" | jq .

如果响应中的 records 数组为空或返回错误，说明此功能未启用。请指导用户：

指标名称统计跟踪器未返回数据。可能的原因：

1. VictoriaMetrics 版本早于 v1.113.0 — 请升级到 v1.113.0+
2. 统计数据最近被重置 — 重启或重置后，跟踪器需要时间来累积查询数据

对于集群模式，必须在 vmstorage 节点上设置此标志。 参见：https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#track-ingested-metrics-usage

如果此功能不可用，请在此处停止。后续工作流程依赖此功能。

如果存在记录，请记下 statsCollectedSince 时间戳，它表示跟踪器已累积数据的时长。收集时间越长，结果越可靠。请告知用户数据收集时间范围，以便他们判断结果的可信度：

• < 1 天：下结论为时尚早 — 许多指标会定期查询（每日仪表板、每周报告、每月告警）
• 1-7 天：适合找出明显未使用的指标，但可能无法涵盖每周模式
• > 7 天：识别确实未使用的指标时，可信度较高
• > 30 天：可信度高 — 如果某个指标在 30 天以上未被查询，它很可能已不再使用

阶段 2：收集并分析

第 1 步：获取所有从未查询过的指标名称

这些指标的 queryRequests: 0，表示它们已被跟踪，但从未被任何查询、仪表板、告警规则或记录规则获取。

请使用较高的限制值，以获取所有指标 — 默认值 1000 通常不够：

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?le=0&limit=50000" | jq .

le=0 参数会筛选出查询次数为 0 的指标。请保存响应中的完整指标名称列表。

步骤 2：区分活跃的浪费与历史噪声

这是关键步骤。metric_names_stats 跟踪器会记录它曾见过的所有指标名称，包括已停用来源中的指标名称，这些来源已不再有活跃时间序列。活跃序列数为 0 的指标会随保留期到期自然清除，不会浪费摄取资源，也无需采取任何行动。

目标是找出正在被主动摄取、但未被查询的指标。

重要：像 container_* 或 node_* 这样的前缀组通常混合了已查询和从未查询的指标名称。例如，container_cpu_usage_seconds_total 可能被频繁查询，而 container_blkio_device_usage_total 从未被查询，但两者都共享 container_ 前缀。计算序列数时，必须只统计具体的、从未查询过的指标名称，而不是整个前缀。

方法：将步骤 1 中从未查询过的指标名称按前缀分组，然后为每组构建仅包含从未查询过的名称的正则表达式，以统计其序列数：

# WRONG — counts ALL container metrics including queried ones:
# count({__name__=~"container_.+"})

# CORRECT — counts only the specific never-queried metric names:
# Build a regex from the actual never-queried names in that prefix group
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query=count({__name__=~"container_blkio_device_usage_total|container_file_descriptors|container_last_seen|container_memory_failcnt|container_sockets|container_tasks_state"})' \
  "$VM_METRICS_URL/api/v1/query" | jq '.data.result[0].value[1]'

对于组中所有指标名称都从未被查询过的前缀组（例如，所有 go_godebug_* 指标），可以直接使用前缀正则表达式，因为不会意外包含已查询的指标。

根据步骤 1 的结果，依次检查主要前缀组。针对每组：

1. 检查此前缀下是否混合了已查询和从未查询的指标，或是否所有指标都从未被查询
2. 对于混合前缀：根据具体的、从未查询过的名称构建正则表达式
3. 对于全部未查询的前缀：直接使用前缀正则表达式
4. 如果 count() 返回 null 或 0 → 这些是仅存在于历史数据中的指标，记录下来，但降低其优先级
5. 如果 count() 返回正数 → 这些是正在被摄取的浪费数据，应优先纳入报告

不要花时间逐一查询数百个序列数为 0 的历史指标。将精力集中在有活跃序列的组上——这些才值得报告。

步骤 3：获取很少被查询的指标

这些指标只被查询过少数几次——可能是一次性探索，而非持续使用。

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?le=5&limit=50000" | jq .

从中减去从未查询过的集合，以筛选出“查询次数为 1-5 次”的组。

步骤 4：获取跟踪的指标总数和活跃序列总数

这能帮助了解未使用指标的占比，以及删除这些指标可能产生的影响。

# Total tracked metric names
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_METRICS_URL/api/v1/status/metric_names_stats?limit=1" | jq '.statsCollectedRecordsTotal'

# Total active time series
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query=count({__name__=~".+"})' \
  "$VM_METRICS_URL/api/v1/query" | jq '.data.result[0].value[1]'

步骤 5：估算每个活跃未使用指标组的序列数

你应该已在步骤 2 中获得这些数字。如果有任何前缀组缺少统计结果，请现在查询——并记住，只统计每组中具体的、从未查询过的指标名称（参见步骤 2 中错误与正确的示例）。

步骤 6：对未使用指标分类

将活跃的未使用指标分组，以便让报告具有可操作性。常见类别包括：

• Kubernetes 基础设施指标（例如，kube_*、container_*、node_* 前缀中未用于任何仪表板或告警的指标）
• 应用指标（没有人为其构建仪表板的自定义应用指标）
• Exporter 冗余（Exporter 通常会生成数百个指标，其中大多数未被使用——例如，go_*、process_*、promhttp_*）
• 已弃用指标（被较新版本替代的旧指标名称）

另用一个简短的章节记录仅存在于历史数据中的指标（活跃序列数为 0）——这些指标无需采取行动，但可以让用户了解哪些指标会自然到期。

阶段 3：报告并提出建议

报告结构

按以下格式呈现调查结果：

## Unused Metrics Report

**Collection window**: [statsCollectedSince date] to now ([N] days)
**Total tracked metric names**: [statsCollectedRecordsTotal]
**Total active time series**: [count]
**Never queried (with active series)**: [count] metrics, ~[M] series ([percentage]% of active series)
**Never queried (historical only, 0 series)**: [count] metrics — will expire with retention, no action needed
**Rarely queried (1-5 times)**: [count] metrics ([percentage]%)
**Queried long time ago (30+ days)**: [count] metrics ([percentage]%)

### Never-Queried Active Metrics by Category

#### [Category Name] — [N] metrics, ~[M] active series
| Metric Pattern | Series Count | Recommendation |
|---|---|---|
| `prefix_*` | ~X,000 | Drop via relabel |

### Rarely-Queried Metrics
[Similar table, but note last query time from lastRequestTimestamp]

### Historical-Only Metrics (No Action Needed)
[Brief list of prefix groups with 0 active series — these are from decommissioned sources and will expire with retention]

### Estimated Impact
- Dropping all never-queried active metrics would eliminate ~[N] series ([X]% of total active)
- Top 3 categories alone account for ~[M] series

建议的操作

对于每类未使用的指标，建议采取以下一种操作：

1. 在 vmagent 处通过 metric_relabel_configs 丢弃（适用于你确定未使用的指标，优先采用此方式）：

# Add to vmagent scrape config or VMServiceScrape/VMPodScrape
metric_relabel_configs:
  - source_labels: [__name__]
    regex: "metric_prefix_.+"
    action: drop

2. 在 vmagent 处通过全局 -relabelConfig 丢弃（适用于所有抓取目标中的广泛模式）：

# vmagent -relabelConfig=relabel.yaml
- source_labels: [__name__]
  regex: "go_memstats_.+|process_virtual_memory_.+|promhttp_.+"
  action: drop

3. 保留但进一步调查（适用于很少查询的指标——可能仍有人需要它们）：

在收集时间段内，这些指标被查询过几次。丢弃之前，请确认它们未用于：

• Grafana 仪表板（在仪表板 JSON 中搜索指标名称）
• 告警规则（检查 VMRule / PrometheusRule CRD）
• 记录规则
• 查询 API 的外部系统

安全注意事项

务必说明以下注意事项：

• 先进行测试：永久丢弃指标之前，先在预发布 vmagent 上使用 drop 规则，确认不会造成问题。
• 检查告警规则和记录规则：仅被记录规则或告警查询的指标，其 queryRequests 计数可能较低，但仍然至关重要。请对照 api/v1/rules 的输出进行检查。
• 只有在查看仪表板后，仪表板查询才会被跟踪：如果某个 Grafana 仪表板中使用了某个指标，但在收集时间段内无人打开该仪表板，该指标就会显示为“未使用”。可以考虑查询 Grafana API 中的仪表板定义，以便进行交叉核对。
• 某些指标具有季节性查询特征：月度或季度报告的查询次数会较低。收集时间段越长，结果越可靠。
• 切勿丢弃 up 或元指标：即使很少直接查询，up、scrape_duration_seconds、scrape_samples_scraped 等指标对于监控系统健康状况也至关重要。