kubesense-metrics

KubeSense メトリクス

メトリクスは VictoriaMetrics に保存され、PromQL（および MetricsQL 拡張機能。詳細は後述）でクエリされます。KubeSense MCP サーバーが必要です。接続と認証については kubesense-mcp を参照してください。

ツール

ツール	目的	備考
get-available-metrics	メトリクス名を一覧表示	search_keywords は大文字と小文字を区別しない部分文字列として AND 検索されます
get-metric-labels	1 つのメトリクスのラベル名を一覧表示	name が必須です
analyze-metrics	PromQL を実行	from_time、to_time、query_type、promql がすべて必須です

3 つのツールはいずれも infrastructure モジュールに対して RBAC を解決します。ここで権限エラーが発生した場合、メトリクスが存在しないのではなく、呼び出し元に infrastructure へのアクセス権がありません。

検索を先に行うルール

メトリクス名を決して推測しないでください。 メトリクス名はデプロイ環境によって異なります。クラスターがどのコレクターを使用しているか（kube-state-metrics と OTel、node-exporter と hostmetrics）によって決まります。存在しないメトリクスに対するクエリは空の結果を返すため、「値がゼロ」と見分けがつきません。

get-available-metrics  →  get-metric-labels  →  analyze-metrics

get-available-metrics のデフォルトは 直近 1 時間です。90 分前に報告された疎なメトリクスは表示されません。存在しないと判断する前に、from_time／to_time の範囲を広げてください。

{ "search_keywords": ["container", "memory"], "limit": 40 }

どちらのキーワードも名前に含まれている必要があります。そのため、["container","memory"] は container_memory_working_set_bytes に一致しますが、container_cpu_usage_seconds_total には一致しません。

get-metric-labels が返すのは ラベル名のみで、値は含まれません。値を確認するには、analyze-metrics でメトリクスをクエリし、結果に含まれる系列ラベルを参照してください。

ラベルの規則（空の結果が発生する最大の原因）

重要

クラスターのラベルは clusterId です。キャメルケースで、アンダースコアはありません。cluster でも、kubesense_cluster でも、cluster_id でもありません。KubeSense 内のすべての kube-state-metrics／cAdvisor 系列にこのラベルが付与されています。

概念	k8s／cAdvisor メトリクスのラベル	OTel hostmetrics のラベル
クラスター	clusterId	kubesense_cluster
ホスト／ノード	node	host_name
環境	—	kubesense_env_type
名前空間	namespace	—
Pod	pod	—
コンテナー	container	—
ワークロード	deployment／daemonset／statefulset（メトリクスファミリーごと）	—

この 2 つのファミリーが存在するのは、クラスターが node-exporter／process-exporter または OpenTelemetry コレクター経由でテレメトリを送信するためです。特定のメトリクスがどちらの規則に従っているかは、推測せずに get-metric-labels を実行して確認してください。

クラウドプロバイダーのメトリクス（AWS／GCP／Azure／Atlas／Confluent／Kong）は、これらのラベルをいずれも持たない 第 3 の規則に従います。詳しくは、後述のクラウドリソースのメトリクスを参照してください。

プロセスメトリクスでは、exporter ファミリーは groupname（{pid}-{command} 形式）を使用します。OTel ファミリーでは、process_pid、process_command_line、process_executable_name に分かれています。

クエリの作成

{
  "from_time": "2026-07-30T10:00:00Z",
  "to_time": "2026-07-30T11:00:00Z",
  "query_type": "range",
  "promql": "sum(rate(container_cpu_usage_seconds_total{container!='',clusterId='prod-us'}[5m])) by (namespace)"
}

• query_type: "range" → 時系列（傾向）。"instant" → 系列ごとに 1 つのスカラー値（合計、現在の状態、上位 N 件）。
• Step は自動計算されます：max(window/30, 15) 秒です。設定することはできません。

インターバルマクロ

rate() のウィンドウがステップより短いと、隙間が生じます。1 時間ウィンドウのステップは 120s なので、rate(x[30s]) では 1 バケット分に満たないサンプルしか取得できず、系列が壊れます。 ステップを上回るリテラル値を選ぶ代わりに、マクロを使用してください。API はクエリが VictoriaMetrics に到達する前に、これらを解決します。

マクロ	解決後の値	用途
$__rate_interval	max(step + 15s, 60s)	rate() と increase() — 既定の選択肢
$__interval	ステップ自体	ウィンドウを 1 バケットと同じ長さにする *_over_time の集約
$__time_filter	クエリ全体の時間範囲（to - from）	ウィンドウ全体の合計を 1 つ取得

sum(rate(container_cpu_usage_seconds_total{container!='',clusterId='prod-us'}[$__rate_interval])) by (namespace)

$__rate_interval はすべてのウィンドウサイズでステップに合わせて変化するため、同じクエリを 5 分間にも 7 日間にも使えます。[5m] のようなリテラル値も引き続き有効で、安全な既定値ですが、 このマクロは、その値を自分で考えなくて済むようにするためのものです。

知っておくべき制限が 2 つあります。

• 解決されるのはこの 3 つだけです。$__interval_ms と $__range は実装されておらず、 展開されないまま VictoriaMetrics に渡されるため、エラーになります。
• ラベル値内のマクロはそのまま残ります。up{job="$__interval"} はリテラル文字列に一致し、 時間の長さには書き換えられません。

コンテナメトリクスの 2 つのルール

1. container_* メトリクスでは、必ず container!='' でフィルターしてください。cAdvisor は container ラベルが空のポッドレベルの集約系列も追加で出力します。このフィルターがないと、 すべての sum() で二重にカウントされます。
2. CPU の単位はコアです。 rate(container_cpu_usage_seconds_total[5m]) はコア単位の値を返します。 KubeSense の UI で使われるミリコアにするには、1000 を掛けてください。

kube_pod_container_resource_limits / _requests

CPU とメモリの両方に使われる単一のメトリクスであり、resource ラベルで区別されます。別々のメトリクスではありません。次のように選択します。

kube_pod_container_resource_limits{resource="memory"}
kube_pod_container_resource_limits{resource="cpu"}

そのため、メモリ使用量と上限の比較は、2 つのメトリクスの減算ではなく結合になります。

sum by (pod, namespace) (container_memory_working_set_bytes{container!=''})
  / sum by (pod, namespace) (kube_pod_container_resource_limits{resource="memory"}) * 100

kube_*_status_phase / _condition はラベルで値を表します

kube_pod_status_phase はフェーズごとに 1 または 0 を返し、フェーズはラベルに含まれます。 そのため、実行中のポッド数を数えるには、ラベルを選択して系列を重複排除します。

count(max by (pod, namespace, clusterId) (kube_pod_status_phase{phase="Running"}) > 0)

ノードも同じ形式です：kube_node_status_condition{condition="Ready",status="true"}。 max by (...) による重複排除は重要です。これを行わないと、重複したラベルセットによって カウントが水増しされます。

MetricsQL の拡張機能

バックエンドは VictoriaMetrics なので、PromQL に加えて MetricsQL を利用できます。KubeSense 自体が 依存している拡張機能は次の 2 つです。

拡張機能	用途
default 0	系列が存在しない場合に値を代入します：sum(...) default 0
drop_empty_series(...)	フィルター後に完全に空になる系列を破棄します
[1h:60s] サブクエリ	集約の集約。例：max_over_time(rate(x[5m])[1h:60s])

標準の Prometheus では動作しませんが、ここでは正しく動作します。

よくあるパターン

目的	クエリ
カウンターの 1 秒あたりのレート	rate(metric[$__rate_interval])
系列全体の集約	sum(...) by (namespace)
ヒストグラムのパーセンタイル	histogram_quantile(0.99, sum(rate(metric_bucket[5m])) by (le))
ウィンドウ全体の合計	increase(metric[$__time_filter])
上位 N 件	topk(10, ...) — query_type: "instant" と組み合わせます
ラベルの正規表現による一致	metric{namespace=~"prod-.*"}
比率をパーセンテージで表示	sum(a) / sum(b) * 100

ヒストグラムのパーセンタイルでは、必ず histogram_quantile の前に sum(rate(...)) by (le) を行ってください。他のラベルでグループ化した生のバケットを渡すと、 意味のない結果になります。

クラウドリソースのメトリクス

AWS CloudWatch、Google Cloud Monitoring、Azure Monitor、MongoDB Atlas、Confluent Cloud、Kong など、クラウドプロバイダー独自のモニタリング API から取得したメトリクスは、同じ VictoriaMetrics インスタンスに保存されますが、まったく異なる規則に従います。

重要

すべてのプロバイダーとリソースタイプのクラウドデータポイントは、1 つの系列名 kubesense_cloud_resource_metric で保存されます。プロバイダー独自のメトリクス名は系列名の一部ではなく、metric_name ラベルです。そのため、get-available-metrics が返す名前は、クラウド系列がいくつあっても常に 1 つだけであり、そこで CPUUtilization を検索しても見つかりません。

kubesense_cloud_resource_metric{provider="aws",resource_type="Ec2Instance",metric_name="CPUUtilization"}

固定ラベルは provider（aws | gcp | azure | mongodbatlas | confluent | kong）、account_id、resource_id、resource_type、metric_name、unit です。これに加えて、region などのコレクターのディメンションが含まれます。clusterId、namespace、pod は存在しないため、Kubernetes クエリからコピーしたセレクターは何も一致しません。

値はラベルに含まれるため、検出はツール呼び出しではなく PromQL のステップです。

count by (resource_type) (kubesense_cloud_resource_metric{provider="aws"})
count by (metric_name, unit) (kubesense_cloud_resource_metric{resource_type="RdsInstance"})

クラウドクエリが正しいか、または気づかないうちに誤っているかを決める 3 つのルール：

1. rate() は使わないでください。 プロバイダーの集計（CloudWatch の Sum／Average、Cloud Monitoring のアライナー、Azure Monitor の集計）は、収集時にすでに適用されています。生の値を使うか、バケットをまとめるために sum_over_time／avg_over_time／max_over_time を使ってください。
2. metric_name と併せて、必ず resource_type を指定してください。 CPUUtilization だけでは、EC2、RDS、ECS、ElastiCache、DocumentDB、Neptune、OpenSearch、Redshift が 1 つの集計に混在します。
3. 収集は 5 分ごとに行われ、15 分間は前方補完されます。 最新のサンプルに新しいタイムスタンプが付与されるため、インスタントクエリは機能します。15 分を超えてデータがない系列は、実際に存在しないのであって、ゼロではありません。ウィンドウは 10m 以上にしてください。

プロバイダーごとの完全なラベル仕様、リソースタイプとそのメトリクス、親リソースに集約される AWS のタイプ（PerformanceInsights または NetworkLoadBalancer というリソースタイプはありません）、およびクエリ例については、 references/cloud-metric-catalog.md を参照してください。

メトリクス、トレース、インフラツールの選択

• リソースの逼迫、飽和状態、容量（CPU、メモリ、ディスク、GPU）→ メトリクス。
• サービス／エンドポイントごとのリクエストレート、レイテンシのパーセンタイル、エラー率 → トレース（analyze-traces）。メトリクスにはリクエスト単位の詳細はありません。
• 「このポッドは再起動しているか／なぜか」や「何が稼働しているか」 → kubesense-infra のツール。すでに結合され、ラベル付けされた同じ情報を、1 回の呼び出しで返します。

低コストのツールで浮かび上がった仮説を定量化して確認するために、メトリクスを使ってください。

メトリクスカタログ

KubeSense が収集するメトリクスファミリー（ポッド、コンテナ、ノード、ワークロード、PVC、ネットワーク、GPU、JVM、プロセスメトリクスの正確な名前）については、 references/metric-catalog.md を参照してください。AWS、GCP、Azure、MongoDB Atlas、Confluent Cloud、Kong のリソースメトリクスについては、 references/cloud-metric-catalog.md を参照してください。

カタログは想定される内容として扱い、検出の代わりにしないでください。存在するファミリーはクラスターのコレクターによって異なり、アプリケーションメトリクスはデプロイごとに異なります。必ず get-available-metrics で確認してください。

ルール

1. PromQL を記述する前に get-available-metrics を実行してください。メトリクス名を決して推測しないでください。
2. ラベルセレクターを記述する前に get-metric-labels を実行してください。また、クラスターラベルが clusterId であることを忘れないでください。
3. すべての container_* メトリクスで container!='' をフィルターしてください。
4. rate() のウィンドウは、自動計算されるステップ（max(window/30, 15)s）以上にしてください。すべてのウィンドウサイズでこの条件を満たす $__rate_interval を優先してください。固定値を使う場合は [5m] が安全です。
5. kube_pod_container_resource_limits／_requests には、resource="cpu"|"memory" セレクターが必要です。これらは別々のメトリクスではなく、1 つのメトリクスです。
6. kube_*_status_phase／_condition では状態がラベルに記録されています。状態を選択し、カウントする前に max by (...) で重複を除去してください。
7. 合計値／現在の状態／上位 N 件には query_type: "instant"、傾向には "range" を指定してください。
8. 結果が空の場合、「一致する時系列がない」ことを意味し、ゼロとは異なります。値を 0 と報告する前に、メトリクスが存在することとラベルが一致することを確認してください。
9. histogram_quantile の前に sum(rate(...)) by (le) を使用してください。
10. まばらなメトリクスでは検索範囲を広げてください。get-available-metrics がデフォルトで検索するのは過去 1 時間のみです。
11. クラウドプロバイダーのメトリクスはすべて、metric_name ラベルにプロバイダーのメトリクス名を持つ単一の系列 kubesense_cloud_resource_metric です。get-available-metrics は使わず、count by (metric_name) (...) で検索してください。
12. クラウドメトリクスに rate() を決して適用しないでください。また、必ず metric_name と併せて resource_type を指定してください。