kubesense-infra

KubeSense 基础设施与清单

遥测数据会告诉你某项服务运行不健康。这些工具会告诉你有哪些资源、 Kubernetes 层面出了什么问题，以及发生了哪些变化——这些上下文能 将症状转化为原因。

需要 KubeSense MCP 服务。有关连接和身份验证，请参阅 kubesense-mcp。

路由 — 请先阅读

用户在询问……	调用	不要调用
“有哪些集群／我可以使用哪些集群名称？”	list-clusters	猜测集群名称——其他所有工具的 clusters 筛选器都是自由文本，不会验证，所以拼写错误会静默地返回空结果
“正在运行什么／有多少个 Pod／Pod 清单”	list-pods	search-logs——日志只会显示记录过日志的 Pod
“为什么这个 Pod 一直重启／陷入崩溃循环／被 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。 名称按顺序传递：绝不要手动输入尚未通过先前调用获取的集群、命名空间、工作负载或 Pod 名称。

工具

工具	用途	必需参数
list-clusters	此部署监控的集群	—
list-nodes	显示 CPU／内存／磁盘压力和就绪状态的节点	—
get-node-detail	单个节点：状态、污点、地址、容量	name
list-pods	显示阶段、重启次数和用量的 Pod	—
get-pod-detail	单个 Pod：容器状态、退出代码、最后状态、QoS	name、namespace、cluster
list-workloads	显示黄金信号（RPS、p95、错误率）的工作负载	—
get-workload-detail	单个工作负载：副本数、4xx/5xx 数量、RPS	workload、namespace
list-issues	KubeSense 已检测到的问题	—
get-infra-issues	Kubernetes 层面的故障：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 拼写为 _precent，而不是 _percent——可接受的值为 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 全部三个参数。这是用于回答 Pod 为何重启的工具——容器状态包含重启原因、退出代码和上次终止状态，而 list-pods 不包含这些信息。

工作负载

应用级视图——每个 Deployment/StatefulSet/DaemonSet 占一行，并已关联来自追踪的黄金信号。

{ "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 才能完成的工作。需要摘要中没有的切片（按端点、状态代码或属性）时，再使用 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 是两次成本低廉的调用，可直接解决大量事件。只有在这两步没有发现问题时，再查看遥测数据。

规则

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. 使用 namespace + workload 限定 get-recent-changes 和 get-infra-issues 的范围；不加范围的调用会产生大量无关结果。
7. 默认时间窗口为 1 小时。如果结果集看起来为空，请先扩大时间窗口，再判断是否确实没有发生任何事情。