kubesense-infra

KubeSense のインフラストラクチャとインベントリ

テレメトリーから、サービスに異常があることは分かります。これらのツールを使うと、何が存在するのか、 Kubernetes レイヤーで何が失敗しているのか、何が変わったのかが分かります。これらのコンテキストが、 症状を原因へと結び付けます。

KubeSense MCP サーバーが必要です。接続と認証については、kubesense-mcp を参照してください。

ルーティング — まずこちらをお読みください

ユーザーの質問…	呼び出すツール	呼び出さないツール
「どのクラスターがあるか／使えるクラスター名は何か？」	list-clusters	クラスター名を推測すること。ほかのすべてのツールの clusters フィルターは検証なしの自由入力なので、入力ミスがあっても何も返されません
「何が実行中か／ポッドはいくつあるか／ポッドのインベントリは？」	list-pods	search-logs — ログが記録されたポッドしか表示されません
「このポッドが再起動する／クラッシュループする／OOMKilled になるのはなぜか？」	get-infra-issues	list-pods（再起動の回数は分かりますが、理由は分かりません）
「何が変わったか／誰かがデプロイしたか／14:00 に壊れたのはなぜか？」	get-recent-changes	ほかのすべて — 最も低コストで根本原因を特定できるため、まずこれを確認してください
「環境全体で何が壊れているか？」	list-issues（プラットフォーム独自の検出）	生のトレースから問題を再導出すること
「ノードの負荷／エビクション／スケジューリングの失敗は？」	list-nodes、続けて get-node-detail	analyze-metrics（問題の発見ではなく、確認に使用します）
「サービスの健全性：アプリごとの RPS、p95、エラー率は？」	list-workloads	analyze-traces（任意の条件での絞り込みには適していますが、健全性の一括確認には過剰です）
「コンテナーの終了コード／直近の状態／再起動の理由は？」	get-pod-detail	list-pods

検出の順序。 list-clusters → list-workloads / list-pods → get-*-detail。 名前は後続の呼び出しに引き継ぎます。前の呼び出しで取得していないクラスター名、名前空間名、ワークロード名、ポッド名を入力しないでください。

ツール

ツール	用途	必須引数
list-clusters	このデプロイで監視しているクラスター	—
list-nodes	CPU／メモリー／ディスクの負荷と準備状態を含むノード	—
get-node-detail	1 つのノード：状態、テイント、アドレス、容量	name
list-pods	フェーズ、再起動回数、使用状況を含むポッド	—
get-pod-detail	1 つのポッド：コンテナーの状態、終了コード、直近の状態、QoS	name、namespace、cluster
list-workloads	ゴールデンシグナル（RPS、p95、エラー率）を含むワークロード	—
get-workload-detail	1 つのワークロード：レプリカ数、4xx／5xx 件数、RPS	workload、namespace
list-issues	KubeSense がすでに検出した問題	—
get-infra-issues	K8s レイヤーの障害：OOM、クラッシュ、プローブ、スケジューリング、イメージの取得	—
get-recent-changes	イメージの更新（デプロイ）とレプリカ数のスケーリング	—

すべてのツールは、デフォルトで過去 1 時間およびアクセス可能なすべてのクラスターを対象にします。 期間を広げるには from_time／to_time（RFC3339）を渡し、対象を絞るには clusters を渡してください。

list-clusters

クラスター名が必要な場合は、最初にこれを呼び出してください。ほかのすべてのツールで使用できる clusters フィルターに対する、唯一の検出手段です。

{ "search": "prod" }

TSV を返します：name、source、env_type、updated_at。

ノード

{ "clusters": ["prod-us"], "sort_by": "memory_usage_precent", "sort_direction": "DESC" }

警告

ノードの sort_by は _percent ではなく _precent と綴ります。指定できる値は memory_usage_precent、disk_usage_precent、cpu_usage_precent です。出力 列では正しい綴り（memory_usage_percent）が使われます。sort_by に _percent を渡しても 並べ替えは行われません。

出力：name、cluster、ready、running_pods、cpu_usage_percent、 memory_usage_percent、disk_usage_percent、kubelet_version、instance_type、 uid、creation_timestamp。

get-node-detail には必須の name と、複数のクラスターに同じ名前のノードがある場合に区別するための省略可能な clusters を渡します。状態、アドレス、ラベル、テイント、および容量／使用状況を、## conditions／## addresses のサブテーブルを含むレコードとして返します。

Pod

{ "namespace": "production", "status": "Pending", "sort_by": "memory_usage", "sort_direction": "DESC" }

• status は Pod のフェーズでフィルタリングします。Running、Pending、Failed、Succeeded、Unknown を指定できます。
• sort_by が受け付けるのは memory_usage または cpu_usage のみです。

出力：name、namespace、cluster、status、owner_kind、owner、node、 restarts、cpu_usage、memory_usage、creation_time。

get-pod-detail には name、namespace、cluster の3つすべてが必要です。Pod が再起動した理由を確認するためのツールです。コンテナーのステータスには再起動理由、終了コード、直近の終了状態が含まれますが、list-pods では確認できません。

ワークロード

アプリケーションレベルのビューです。トレースから取得したゴールデンシグナルをあらかじめ結合した、Deployment／StatefulSet／DaemonSet ごとに1行の情報を表示します。

{ "namespace": "production", "kind": "Deployment", "sort_by": "error_rate", "sort_direction": "DESC" }

sort_by が受け付けるのは rps、p95、errors、error_rate、restarts です。

出力：name、namespace、cluster、kind、ready、desired、restarts、rps、 p95、error_rate、issue_count、service_protocols。

ヘルスチェックにはこちらを使います。ワークロードごとに analyze-traces を実行する代わりに、1回の呼び出しで確認できます。サマリーにない切り口（エンドポイント、ステータスコード、属性別）が必要な場合は、analyze-traces に切り替えてください。

list-issues

KubeSense 独自の問題検出機能です。ワークロード間のエラー、レイテンシ、接続の問題を検出します。生のテレメトリから問題を再導出するより、こちらを優先してください。

出力：issue_id、kind、cluster、primary_workload、primary_namespace、 associate_workload、issue_reason、return_code、subtype、sum_issue_count、 max_last_seen。

associate_workload は接続問題のもう一方の側、つまり primary_workload が到達できなかった依存先です。

get-infra-issues

クラスターイベントから取得した、Kubernetes レイヤーの障害です。OOM／CrashLoop／プローブ失敗を調べるツールです。

{ "namespace": "production", "workload": "checkout", "reason": "OOMKilling" }

既知の reason 値：OOMKilling、BackOff、Unhealthy、FailedScheduling、 FailedMount、ImagePullBackOff、NodeNotReady。すべての障害モードを確認するには reason を省略してください。追跡対象がわかってから絞り込んでください。

出力：reason、type、workload、object、namespace、exit_code（クラッシュ時のみ）、 message、count、last_seen。デフォルトの上限は50、最大は200です。

**レイヤーごとの使い分け：**インフラの障害にはこのツールを使います。アプリケーションのエラーやレイテンシには analyze-traces／search-traces を使います。変更点の確認には get-recent-changes を使います。

get-recent-changes

クラスターイベントから取得した、イメージの更新（デプロイ）とレプリカのスケーリングです。調査では通常、最初に確認する項目です。「壊れる直前に何が変わったか」は、最小限のコストで検証できる仮説です。

{ "namespace": "production", "workload": "checkout", "kind": "image_update" }

kind は image_update または scaling です。両方を対象にする場合は省略してください。出力：kind、workload、namespace、object、detail、when。detail には kubesense: dev-v1.2.1279 -> dev-v1.2.1280 や replicas 1 -> 0 のような情報が表示されます。デフォルトの上限は50、最大は200です。

namespace と workload で対象を絞り込みます。どちらも省略できますが、指定を強くおすすめします。負荷の高いクラスター全体を対象にした呼び出しでは、大半がノイズになります。

調査パターン

症状 → 状況 → 原因の順に、最も低コストのシグナルから確認します。

1. get-recent-changes    namespace+workload → did we just deploy or scale?
2. get-infra-issues      same scope        → is the platform killing it (OOM, probes, sched)?
3. list-pods / get-pod-detail               → restart counts, exit codes, last state
4. analyze-traces / search-logs              → application-level errors and latency
5. analyze-metrics                           → confirm resource pressure quantitatively

手順1〜2は、インシデントの大部分をその場で解決できる、低コストな2回の呼び出しです。これらで問題が見つからなかった場合に、テレメトリを確認してください。

ルール

1. clusters でフィルタリングする前に、必ず list-clusters を実行してください。フィルターは検証されないフリーテキストです。名前が間違っていると、「データなし」とまったく同じ結果が返されます。
2. 名前は一覧取得から詳細取得へ引き継いでください。Pod、ノード、ワークロード、または名前空間の名前を決して推測しないでください。
3. get-pod-detail には name、namespace、cluster が必要です。get-workload-detail には workload、namespace が必要です。対応する list-* 呼び出しで確認してください。
4. ノードの sort_by では、誤記された _precent を使用します。出力列では _percent を使用します。
5. 生のテレメトリーから問題を再導出するより、list-issues / get-infra-issues を優先してください。プラットフォームがすでに問題を検出しています。
6. get-recent-changes と get-infra-issues は、namespace と workload で範囲を絞ってください。範囲を指定しない呼び出しはノイズが多くなります。
7. デフォルトの時間範囲は1時間です。結果セットが空に見える場合は、何も起きなかったと結論づける前に時間範囲を広げてください。