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 は、各メトリクス名がクエリで取得された回数と、最後に取得された日時を追跡します。これは v1.113.0 から利用可能な metric_names_stats API によって行われます。取り込まれたメトリクスと実際にクエリされたメトリクスを比較することで、誰も使っていないメトリクスを見つけ、安全に削除できます。

ワークフローは次の 3 つのフェーズで構成されます。

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_* プレフィックス）
• アプリケーションメトリクス（ダッシュボードが作成されていないカスタムアプリメトリクス）
• エクスポーターの肥大化（エクスポーターは多くの場合、数百のメトリクスを出力しますが、その大半は未使用です。例：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. metric_relabel_configs を使用して vmagent で破棄する（未使用であると確信できるメトリクスに推奨）：

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

2. グローバルな -relabelConfig を使用して vmagent で破棄する（すべてのスクレイプ対象に適用する広範なパターンの場合）：

# 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 などのメトリクスは、直接クエリされる頻度が低くても、監視の健全性を把握するうえで不可欠です。