kubesense-metrics

KubeSense Metrics

指标存储在 VictoriaMetrics 中，并使用 PromQL 查询（以及 MetricsQL 扩展，见下文）。需要 KubeSense MCP 服务；连接和身份验证请参见 kubesense-mcp。

工具

工具	用途	备注
get-available-metrics	列出指标名称	search_keywords 使用 AND 匹配，不区分大小写的子字符串
get-metric-labels	列出某个指标上的标签名称	必须提供 name
analyze-metrics	执行 PromQL	必须提供 from_time、to_time、query_type、promql

这三个工具都会针对 infrastructure 模块进行 RBAC 权限检查——此处的权限错误表示调用方没有基础设施访问权限，而不是指标不存在。

优先发现规则

切勿猜测指标名称。 指标名称因部署而异，取决于集群使用的采集器（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（因指标系列而异）	—

集群会通过 node-exporter/process-exporter 或 OpenTelemetry 收集器发送遥测数据，因此存在这两类标签。请运行 get-metric-labels 查看特定指标使用哪种惯例，不要自行假设。

云服务商指标（AWS/GCP/Azure/Atlas/Confluent/Kong）采用第三种惯例，不包含上述任何标签——请参见下文的云资源指标。

进程指标：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" → 每个时间序列返回一个标量（总量、当前状态、Top-N）。
• Step 会自动计算：max(window/30, 15) 秒。无法手动设置。

时间间隔宏

窄于步长的 rate() 窗口会留下间隙——1 小时窗口的步长为 120s，因此 rate(x[30s]) 采样的数据不足一个桶，返回的序列会出错。 与其选择一个刚好大于步长的字面值，不如使用宏。API 会在查询发送到 VictoriaMetrics 之前解析这些宏：

宏	解析为	用途
$__rate_interval	max(step + 15s, 60s)	rate() 和 increase()——默认选择
$__interval	步长本身	*_over_time 汇总，其中窗口应等于一个桶
$__time_filter	查询的整个时间范围（to - from）	计算窗口内的单个总值

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

$__rate_interval 会随各种窗口大小的步长变化，因此同一个查询在 5 分钟和 7 天范围内都能正常工作。像 [5m] 这样的字面值仍然有效，也仍是安全的默认值，但宏的存在就是为了让你不必再费心推算。

有两点限制需要了解：

• 只会解析这三个宏。$__interval_ms 和 $__range 未实现， 会未经展开就发送到 VictoriaMetrics，导致失败。
• 标签值中的宏会保持原样——up{job="$__interval"} 匹配的是 字面字符串，不会被改写为时长。

两条容器指标规则

1. 对 container_* 指标始终添加 container!='' 过滤条件。cAdvisor 会额外生成一条 container 标签为空的 Pod 级汇总序列；如果不加过滤条件，每个 sum() 都会重复计数。
2. CPU 的单位是核数。rate(container_cpu_usage_seconds_total[5m]) 返回核数； 乘以 1000 可得到毫核，这也是 KubeSense 自身 UI 使用的单位。

kube_pod_container_resource_limits / _requests

CPU 和内存共用同一个指标，通过 resource 标签进行区分，而不是使用不同指标。选择方式如下：

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

因此，内存使用量与限制值的比较需要进行连接，而不是对两个指标相减：

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 的序列，并将阶段放在标签中——因此，要统计运行中的 Pod，需要选择相应标签并对序列去重：

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 本身依赖其中的两项扩展：

扩展	用途
default 0	在序列不存在时替换为指定值：sum(...) default 0
drop_empty_series(...)	丢弃过滤后完全为空的序列
[1h:60s] 子查询	对汇总结果再次进行汇总，例如 max_over_time(rate(x[5m])[1h:60s])

这些用法无法用于原版 Prometheus，但在这里是正确的。

常见模式

目标	查询
计数器的每秒速率	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

计算直方图百分位数时，务必先执行 sum(rate(...)) by (le)，再 调用 histogram_quantile——传入按其他标签分组的原始桶会产生无意义的结果。

云资源指标

从云提供商自己的监控 API 拉取的指标——AWS CloudWatch、Google Cloud Monitoring、Azure Monitor、MongoDB Atlas、Confluent Cloud、Kong——也位于同一个 VictoriaMetrics 实例中，但遵循完全不同的约定。

重要

每个云数据点，无论提供商和资源类型，都存储在同一个 序列名称下：kubesense_cloud_resource_metric。提供商自身的指标名称是 metric_name 标签，而非序列名称的一部分。因此，无论存在多少云序列， get-available-metrics 都只会返回一个名称；搜索 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"})

以下三条规则决定云查询是正确还是会悄然出错：

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 混合 聚合在一起。
3. 采集每 5 分钟进行一次，并向前填充 15 分钟。 最新样本会重新加盖时间戳， 因此即时查询有效；静默超过 15 分钟的序列确实不存在，而不是值为零。窗口应 保持在 10m 或以上。

完整的标签约定、各提供商的资源类型及其指标、汇总到父级的 AWS 类型（没有 PerformanceInsights 或 NetworkLoadBalancer 资源类型），以及查询示例： references/cloud-metric-catalog.md。

选择指标、Trace 还是基础设施工具

• 资源压力、饱和度、容量（CPU、内存、磁盘、GPU）→ 指标。
• 请求速率、延迟百分位数、每个服务/端点的错误率 → Trace （analyze-traces）。指标没有逐请求详情。
• “这个 Pod 是否在重启 / 为什么”或“正在运行什么” → kubesense-infra 工具；它们通过一次调用返回已关联并标记 的相同事实。

使用指标来量化并确认成本更低的工具发现的假设。

指标目录

如需了解 KubeSense 收集的指标系列——Pod、容器、节点、 工作负载、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) 秒）。优先使用 $__rate_interval，它能确保在任何窗口大小下都满足要求；字面量 [5m] 也是安全的。
5. kube_pod_container_resource_limits/_requests 需要 resource="cpu"|"memory" 选择器——它们是同一个指标，不是两个指标。
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. 云提供商指标都属于同一个序列——kubesense_cloud_resource_metric——提供商的指标名称位于 metric_name 标签中。使用 count by (metric_name) (...) 发现这些指标，切勿使用 get-available-metrics。
12. 切勿对云指标使用 rate()，并始终在 metric_name 旁指定 resource_type。