Kubernetes Metrics Reference（v1.37）解读：读懂组件导出的 Prometheus 指标、稳定性契约与全量指标清单

2026-09-06 19:05:13作者：邵娇湘

本篇指南面向需要对 Kubernetes 控制面与数据面做监控、告警与 SLI 设计的技术人员。文中以当前仓库 hack/tools/instrumentation/documentation/documentation.md 这份自动生成的 Kubernetes Metrics Reference（v1.37）为主体，讲解各组件（kube-apiserver、kube-controller-manager、kube-scheduler、kubelet、kube-proxy、cloud-controller-manager）通过 HTTP 端点导出的 627 条指标，剖析 STABLE / BETA / ALPHA 三级稳定性契约及其对告警与仪表盘的意义，并结合仓库内的文档生成工具链说明这些清单的来源与维护方式。读完你将能正确解读指标条目的各个字段（类型、标签、组件端点、废弃版本），判断哪些指标可以安全地写入长期告警，并能依据源码在仓库中追索每条指标的定义与归属。

一、这份文档是什么：Kubernetes Metrics Reference

在 Kubernetes 主仓库中，hack/tools/instrumentation/documentation/documentation.md 是一份自动生成（front matter 中标明 auto_generated: true）的指标参考文档，标题为 Kubernetes Metrics Reference，content_type: reference。文件头部注释显示其当前对应 v1.37（生成于 2026 Aug 28）。

文档原文开宗明义地指出：

This page details the metrics that different Kubernetes components export. You can query the metrics endpoint for these components using an HTTP scrape, and fetch the current metrics data in Prometheus format.

也就是说，任何运行中的 Kubernetes 组件都会暴露一个 metrics 端点，外部可用 HTTP 抓取（scrape）的方式读取当前时刻的指标值，数据格式即为 Prometheus 文本格式。

从内容规模看，这份参考共收录 627 条指标，按稳定性分成三节：

List of Stable Kubernetes Metrics：37 条；
List of Beta Kubernetes Metrics：65 条；
List of Alpha Kubernetes Metrics：525 条。

每一条指标都给出了完整的元数据描述。参考文档本身是“全量清单 + 契约说明”，本文在此基础上补充字段语义、端点规划、生成机制与使用建议，方便你把它真正用起来。

二、指标在哪里暴露：端点与抓取方式

Kubernetes 各组件把指标以 Prometheus 格式暴露在 HTTP 端点上。默认端点约定为 /metrics，另有若干特例。这些映射关系由仓库中的 hack/tools/instrumentation/endpoint-mappings.yaml 统一维护，其解析规则是：endpointMappings 从上到下按顺序匹配，第一个命中的规则生效；没有任何规则命中时使用 defaultEndpoint: /metrics。

端点规划要点如下：

端点	含义	覆盖范围
`/metrics`	默认端点	绝大多数组件指标，例如 kube-apiserver、kube-controller-manager、kube-scheduler 等
`/metrics/resource`	容器 / Pod / 节点资源用量指标	命中源码路径 `pkg/kubelet/metrics/collectors/resource_metrics.go` 的指标，如 `container_cpu_usage_seconds_total`、`node_memory_working_set_bytes`
`/metrics/probes`	探针执行指标	命中 `pkg/kubelet/prober/` 的指标，如 `prober_probe_total`
`/metrics/slis`	健康检查类 SLI 指标	命中 `staging/src/k8s.io/component-base/metrics/prometheus/slis` 的指标，如 `kubernetes_healthcheck`、`kubernetes_healthchecks_total`

由此可以解释文档中每个条目的 “Components” 字段为何会附带端点后缀：例如 container_memory_working_set_bytes 标注为 kubelet (/metrics/resource)，而 kubernetes_healthcheck 则在全部六个核心组件上都以 (/metrics/slis) 暴露。

实际抓取时，可以直接对端点发 HTTP GET 请求，例如：

# 访问 kube-apiserver 的默认指标端点（需携带凭据，示意）
curl -sk -H "Authorization: Bearer $(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
  https://<kube-apiserver-address>:6443/metrics

# 本地 kubelet 的 cadvisor 风格资源端点（示意）
curl -sk https://127.0.0.1:10250/metrics/resource

生产环境通常由 Prometheus 等采集器定时抓取这些端点，随后在 PromQL 中查询与聚合。文档中所有指标均遵循 Prometheus 命名与暴露格式（命名合规性另有 hack/verify-metrics-naming.sh 在 CI 中校验）。

三、稳定性分级：STABLE / BETA / ALPHA 的 API 契约

这份参考最核心的价值，是把每条指标按 API 稳定性承诺分成三级。理解这套分级，是决定“能否把某条指标写进长期告警/仪表盘”的前提。

STABLE（稳定）

文档原文给出严格定义：

Stable metrics observe strict API contracts and no labels can be added or removed from stable metrics during their lifetime.

翻译并展开：稳定指标在整个生命周期内遵循严格的 API 契约——既不允许增加标签，也不允许删除标签。这意味着基于稳定指标建立的仪表盘、告警表达式、报表在跨版本升级时不会因标签集合变化而失效。v1.37 中共有 37 条稳定指标（详见本文第六节），它们是最值得优先使用的观测对象。

BETA（测试）

文档原文：

Beta metrics observe a looser API contract than its stable counterparts. No labels can be removed from beta metrics during their lifetime, however, labels can be added while the metric is in the beta stage. This offers the assurance that beta metrics will honor existing dashboards and alerts, while allowing for amendments in the future.

即：Beta 指标在存续期间标签只增不减——不能删除标签，但允许在 Beta 阶段追加标签。这一“半契约”既保证既有仪表盘与告警不被打断，又给指标演进留出了空间。v1.37 共有 65 条 Beta 指标（详见第七节），可以将它们视为“可谨慎使用、但需关注后续标签增补”的指标。

ALPHA（实验）

文档原文：

Alpha metrics do not have any API guarantees. These metrics must be used at your own risk, subsequent versions of Kubernetes may remove these metrics altogether, or mutate the API in such a way that breaks existing dashboards and alerts.

Alpha 指标没有任何 API 保证：后续版本可能整体移除这些指标，或改动其结构（名称、标签、类型）从而破坏现有仪表盘与告警。v1.37 中有 525 条 Alpha 指标，使用时风险自担——它们更适合用于临时排障与观察，而不是沉淀为长期告警。

稳定性如何被强制约束

从源码结构看，稳定性分级并非仅靠文档自觉维护，而是有一套回归测试机制：

稳定指标的“黄金清单”固化在 hack/tools/instrumentation/testdata/stable-metrics-list.yaml，README 说明一旦有人增删稳定指标，回归测试就会失败，且变更必须经 sig-instrumentation 评审；
新增/调整稳定指标后需要运行 hack/update-generated-stable-metrics.sh 更新清单；
稳定性框架本身位于 staging/src/k8s.io/component-base/metrics（对应文档中的 sharedPaths），各核心组件共享该基础设施；
文档生成阶段还会标注指标的废弃版本（Deprecated Versions）。例如稳定指标 apiserver_storage_objects 标注自 1.34.0 起废弃，并建议改用 apiserver_resource_objects；Alpha 指标 apiserver_cache_list_fetched_objects_total、apiserver_cache_list_returned_objects_total 标注自 1.37.0 起废弃。废弃过程本身也被计入 registered_metrics_total 指标的 deprecated_version 标签，便于观测整体注册情况。

四、单条指标条目的信息结构

文档中每条指标都包含一组结构化字段，其语义对应 hack/tools/instrumentation/internal/metric/metric.go 中的 Metric 结构体（name/namespace/subsystem/help/type/stabilityLevel/labels/constLabels/deprecatedVersion/componentEndpoints 等）。字段含义如下：

字段	含义	说明
指标名（`metric_name`）	完全限定名（FQN）	由 namespace、subsystem、name 经 `metrics.BuildFQName` 拼接而成，即你在 PromQL 中直接书写的名字
Help	指标含义描述	一句话解释该指标度量什么、数值单位与语义
Stability Level	稳定性级别	`STABLE` / `BETA` / `ALPHA` 之一
Type	指标类型	文档中出现：`Counter`、`Gauge`、`Histogram`、`Summary`、`TimingRatioHistogram`、`Custom`。前四类为 Prometheus 标准类型；`TimingRatioHistogram` 用于 APF 席位利用率这类“时间占比”观测（如 `apiserver_flowcontrol_priority_level_seat_utilization`）；`Custom` 用于由自定义 collector 输出的资源类指标（如 kubelet 的容器/节点资源指标）
Labels（可变标签）	区分维度	聚合查询的切分维度，例如 `verb`、`resource`、`code`、`namespace`
Const Labels（常量标签）	固定附加标签	该指标始终携带的固定键值，例如 `phase:executing`
Components（组件端点）	暴露位置	标明由哪个组件在哪个端点导出，例如 `kube-apiserver (/metrics)`、`kubelet (/metrics/resource)`
Deprecated Versions	废弃版本	若存在，表示该指标自某版本起被废弃（但仍在文档中列出）

例如稳定指标 apiserver_request_total 的完整字段为：Counter 类型，标签 code、component、dry_run、group、resource、scope、subresource、verb、version，由 kube-apiserver (/metrics) 导出。这些标签组合恰好覆盖了 HTTP 响应码、API 资源与请求动作等多个维度，足够支撑绝大多数流量与错误率分析。

五、文档如何生成：仓库内的指标文档流水线

参考文档并非手写，而是由 hack/tools/instrumentation/ 下的一组 Go 工具与 Shell 脚本流水线生成，理解它有助于判断“这份清单可信度与时效性如何”。

大致流程（从仓库文件推断并结合 README 佐证）：

静态扫描注册点：通过 hack/tools/instrumentation/decode_metric.go 等对代码库做静态分析，找出各组件中注册的指标定义；
按路径归属组件与端点：将每个指标源码所在文件路径与 hack/tools/instrumentation/endpoint-mappings.yaml 中的 coreComponents 列表匹配，得出该指标由哪个（些）组件导出；sharedPaths 指向 staging/src/k8s.io/component-base/——该路径下的通用指标（如健康检查、workqueue 系列）会被归属到全部核心组件。若指标落在未映射的目录，生成时会打出类似 WARNING: found 1 metric(s) in ... but could not infer component endpoints 的告警，提示维护者补充映射；
生成清单：运行 hack/tools/instrumentation/update-documentation-metrics.sh 生成中间清单 documentation-list.yaml；
渲染 Markdown：运行 hack/tools/instrumentation/update-documentation.sh 读取版本号并调用 hack/tools/instrumentation/documentation/main.go。后者把指标按稳定性（STABLE/BETA/ALPHA）分组、按 FQN 排序（见 internal/metric/metric.go 中的 ByFQName），再套用内置的 Go text/template（模板里写死了三级稳定性契约的说明文字），渲染出 documentation.md；

对外发布：hack/tools/instrumentation/README.md 说明，需要把成品复制到 Kubernetes 官网文档目录，例如：

cp ./hack/tools/instrumentation/documentation/documentation.md $WEBSITE_ROOT/content/en/docs/reference/instrumentation/metrics.md

同时，稳定性与命名还有配套门禁：hack/update-generated-stable-metrics.sh 维护稳定指标清单、hack/verify-metrics-naming.sh 校验 Prometheus 命名规范，hack/tools/instrumentation/test-verify.sh / test-update.sh 用于本地验证与更新测试金样（golden list）。

因此，本文引用的 627 条指标及其标签、端点与废弃版本信息，均可在仓库源码与上述 YAML 配置中得到印证，而不是凭空整理的二手数据。

六、STABLE 指标全清单（37 条，v1.37）

稳定指标是唯一“一生都不允许增删标签”的指标，最适合纳入生产告警与容量 SLI。以下是文档中 Stable 一节的完整清单，按暴露组件归类，并补充每条的类型、标签与用途说明。

kube-apiserver 请求生命周期（/metrics）

指标	类型	标签	说明
`apiserver_admission_controller_admission_duration_seconds`	Histogram	name, operation, rejected, type	准入控制器延迟直方图，按名称、操作、API 资源以及阶段（validate/admit）细分
`apiserver_admission_step_admission_duration_seconds`	Histogram	operation, rejected, type	准入“子步骤”延迟直方图，按操作、API 资源与步骤类型细分
`apiserver_admission_webhook_admission_duration_seconds`	Histogram	name, operation, rejected, type	准入 Webhook 调用延迟直方图，按 Webhook 名称与操作细分
`apiserver_current_inflight_requests`	Gauge	request_kind	上一秒内该 apiserver 每种请求类别实际占用的最大并发限流值，用于观察 APF/并发水位
`apiserver_longrunning_requests`	Gauge	component, group, resource, scope, subresource, verb, version	当前活跃的长连接请求（如 WATCH）计数，按动作与资源细分；并非所有请求都被如此追踪
`apiserver_request_duration_seconds`	Histogram	component, dry_run, group, resource, scope, subresource, verb, version	API 请求响应延迟分布（秒），是 apiserver 延迟 SLI 的核心数据源
`apiserver_request_total`	Counter	code, component, dry_run, group, resource, scope, subresource, verb, version	API 请求总数计数器，按动词、dryRun、资源与 HTTP 响应码细分
`apiserver_requested_deprecated_apis`	Gauge	group, removed_release, resource, subresource, version	已被请求的废弃 API 计数，按 API 组/版本/资源以及计划移除版本细分，用于评估废弃 API 使用面
`apiserver_response_sizes`	Histogram	component, group, resource, scope, subresource, verb, version	API 响应体积分布（字节）
`apiserver_storage_objects`	Gauge	resource	最近一次检查时各 kind 的存量对象数量；抓取出错时取值为 -1。自 1.34.0 废弃，建议改用 `apiserver_resource_objects`
`apiserver_storage_size_bytes`	Custom	storage_cluster_id	后端存储数据库文件物理分配的字节数（即 etcd 侧文件大小）

kube-controller-manager 的控制器指标（/metrics）

指标	类型	标签	说明
`cronjob_controller_job_creation_skew_duration_seconds`	Histogram	（无）	CronJob 计划运行时刻与对应 Job 实际创建时刻之间的时间差，衡量调度准时性
`job_controller_job_pods_finished_total`	Counter	completion_mode, result	已被完整追踪的已结束 Pod 数量
`job_controller_job_sync_duration_seconds`	Histogram	action, completion_mode, result	单次同步一个 Job 所花费的时间
`job_controller_job_syncs_total`	Counter	action, completion_mode, result	Job 同步次数
`job_controller_jobs_finished_total`	Counter	completion_mode, reason, result	已结束的 Job 数量
`node_collector_evictions_total`	Counter	zone	自当前 NodeController 实例启动以来发生的节点驱逐次数，按可用区细分

kubelet 资源用量指标（/metrics/resource）

这类指标类型为 Custom，由 kubelet 的 resource 端点导出，是容器可观测性（cAdvisor 之外的另一套稳定来源）的基础。

指标	类型	标签	说明
`container_cpu_usage_seconds_total`	Custom	container, pod, namespace	容器累计消耗的 CPU 时间（core-seconds）
`container_memory_working_set_bytes`	Custom	container, pod, namespace	容器当前工作集内存（字节）
`container_start_time_seconds`	Custom	container, pod, namespace	容器自 Unix 纪元起的启动时间（秒）
`node_cpu_usage_seconds_total`	Custom	（无）	节点累计消耗的 CPU 时间（core-seconds）
`node_memory_working_set_bytes`	Custom	（无）	节点当前工作集内存（字节）
`pod_cpu_usage_seconds_total`	Custom	pod, namespace	Pod 累计消耗的 CPU 时间（core-seconds）
`pod_memory_working_set_bytes`	Custom	pod, namespace	Pod 当前工作集内存（字节）
`resource_scrape_error`	Custom	（无）	抓取容器指标出错时为 1，否则为 0，用于快速发现资源采集故障

kube-scheduler 调度指标（/metrics）

指标	类型	标签	说明
`kube_pod_resource_limit`	Custom	namespace, pod, node, scheduler, priority, resource, unit	集群工作负载的资源上限声明（按 Pod 拆分），即调度器与 kubelet 期望的资源量与单位
`kube_pod_resource_request`	Custom	namespace, pod, node, scheduler, priority, resource, unit	集群工作负载的资源请求量声明（按 Pod 拆分）
`scheduler_framework_extension_point_duration_seconds`	Histogram	extension_point, profile, status	运行某个扩展点全部插件所需延迟
`scheduler_pending_pods`	Gauge	queue	各调度队列中的待调度 Pod 数：active（activeQ）、backoff（backoffQ）、unschedulable（尝试后失败）、gated（被门控从未尝试）、incomplete/pending（PodGroup 相关队列）
`scheduler_pod_scheduling_attempts`	Histogram	（无）	Pod 成功调度前的尝试次数分布
`scheduler_preemption_attempts_total`	Counter	（无）	集群至今的抢占尝试总数
`scheduler_preemption_victims`	Histogram	（无）	单次抢占所选受害者数量分布
`scheduler_queue_incoming_pods_total`	Counter	event, queue	按事件类型与队列类型统计进入调度队列的 Pod 数
`scheduler_schedule_attempts_total`	Counter	profile, result	调度尝试次数；result 为 `unschedulable`（不可调度）或 `error`（调度器内部错误）
`scheduler_scheduling_attempt_duration_seconds`	Histogram	profile, result	单次调度尝试延迟（调度算法 + 绑定），秒

全部核心组件的健康检查 SLI（/metrics/slis）

指标	类型	标签	暴露组件
`kubernetes_healthcheck`	Gauge	name, type	cloud-controller-manager、kube-apiserver、kube-controller-manager、kube-proxy、kube-scheduler、kubelet（均在 `/metrics/slis`）
`kubernetes_healthchecks_total`	Counter	name, status, type	同上

kubernetes_healthcheck 记录单次健康检查的结果，kubernetes_healthchecks_total 累计全部健康检查结果并按 status 细分，二者是构造组件可用性 SLI（SLO）的标准素材。

典型 PromQL 用法（示意）

# apiserver 每秒请求量（按响应码）
sum by (code) (rate(apiserver_request_total[5m]))

# apiserver 写请求 P99 延迟（Histogram 聚合示意）
histogram_quantile(0.99, sum(rate(apiserver_request_duration_seconds_bucket{verb=~"POST|PUT|PATCH|DELETE"}[5m])) by (le))

# 调度队列堆积
scheduler_pending_pods{queue="active"}

# 组件健康检查失败即告警
kubernetes_healthcheck{name=~"etcd|readyz|livez"} != 1

七、BETA 指标（65 条）：标签只增不减的演进中指标

Beta 指标“可删标签被禁止、可增标签被允许”，因此比 Alpha 可靠，但仍要留意未来标签增补。文档中 Beta 一节按子系统可归纳如下（此处列出全部 65 条的名称、类型、标签与所属组件/端点，便于检索）：

认证 / 授权配置热加载（kube-apiserver）

指标	类型	标签
`apiserver_authentication_config_controller_automatic_reload_last_timestamp_seconds`	Gauge	apiserver_id_hash, status
`apiserver_authentication_config_controller_automatic_reloads_total`	Counter	apiserver_id_hash, status
`apiserver_authorization_config_controller_automatic_reload_last_timestamp_seconds`	Gauge	apiserver_id_hash, status
`apiserver_authorization_config_controller_automatic_reloads_total`	Counter	apiserver_id_hash, status

APF（API Priority and Fairness）流控子系统（kube-apiserver）

指标	类型	标签
`apiserver_flowcontrol_current_executing_requests`	Gauge	flow_schema, priority_level
`apiserver_flowcontrol_current_executing_seats`	Gauge	flow_schema, priority_level
`apiserver_flowcontrol_current_inqueue_requests`	Gauge	flow_schema, priority_level
`apiserver_flowcontrol_dispatched_requests_total`	Counter	flow_schema, priority_level
`apiserver_flowcontrol_nominal_limit_seats`	Gauge	priority_level
`apiserver_flowcontrol_priority_level_seat_utilization`	TimingRatioHistogram	priority_level；常量标签 phase:executing
`apiserver_flowcontrol_rejected_requests_total`	Counter	flow_schema, priority_level, reason
`apiserver_flowcontrol_request_wait_duration_seconds`	Histogram	execute, flow_schema, priority_level

CEL、Watch、声明式校验与 Webhook 证书（kube-apiserver）

指标	类型	标签
`apiserver_cel_compilation_duration_seconds`	Histogram	（无）
`apiserver_cel_evaluation_duration_seconds`	Histogram	（无）
`apiserver_watch_events_sizes`	Histogram	group, resource, version
`apiserver_watch_events_total`	Counter	group, resource, version
`apiserver_watch_list_duration_seconds`	Histogram	group, resource, scope, version
`apiserver_webhooks_x509_insecure_sha1_total`	Counter	（无）
`apiserver_webhooks_x509_missing_san_total`	Counter	（无）
`apiserver_validation_declarative_validation_mismatch_total`	Counter	（无）
`apiserver_validation_declarative_validation_panic_total`	Counter	（无）
`apiserver_storage_events_received_total`	Counter	group, resource

ValidatingAdmissionPolicy（kube-apiserver）

指标	类型	标签
`apiserver_validating_admission_policy_check_duration_seconds`	Histogram	enforcement_action, error_type, policy, policy_binding
`apiserver_validating_admission_policy_check_total`	Counter	enforcement_action, error_type, policy, policy_binding

控制器管理器：EndpointSlice / HPA / Job（kube-controller-manager）

指标	类型	标签
`endpoint_slice_controller_desired_endpoint_slices`	Gauge	（无）
`endpoint_slice_controller_endpoints_added_per_sync`	Histogram	（无）
`endpoint_slice_controller_endpoints_desired`	Gauge	（无）
`endpoint_slice_controller_endpoints_removed_per_sync`	Histogram	（无）
`endpoint_slice_controller_num_endpoint_slices`	Gauge	（无）
`endpoint_slice_controller_services_count_by_traffic_distribution`	Gauge	traffic_distribution
`horizontal_pod_autoscaler_controller_metric_computation_duration_seconds`	Histogram	action, error, metric_type
`horizontal_pod_autoscaler_controller_metric_computation_total`	Counter	action, error, metric_type
`horizontal_pod_autoscaler_controller_reconciliation_duration_seconds`	Histogram	action, error
`horizontal_pod_autoscaler_controller_reconciliations_total`	Counter	action, error
`job_controller_pod_failures_handled_by_failure_policy_total`	Counter	action
`job_controller_terminated_pods_tracking_finalizer_total`	Counter	event

HPA 系列指标中的 action 取值限定为 scale_down / scale_up / none，error 取值限定为 spec / internal / none；文档 help 明确：若一次 reconcile 同时发生 spec 与 internal 两类错误，error 标签只记录先发生的那一个。

kubelet：镜像卷（Image Volume）与存储操作

指标	类型	标签	端点
`kubelet_image_volume_mounted_errors_total`	Counter	（无）	kubelet (/metrics)
`kubelet_image_volume_mounted_succeed_total`	Counter	（无）	kubelet (/metrics)
`kubelet_image_volume_requested_total`	Counter	（无）	kubelet (/metrics)
`storage_operation_duration_seconds`	Histogram	migrated, operation_name, status, volume_plugin	kubelet (/metrics)
`volume_operation_total_seconds`	Histogram	operation_name, plugin_name	kubelet (/metrics)
`prober_probe_total`	Counter	container, namespace, pod, pod_uid, probe_type, result	kubelet (/metrics/probes)

kube-scheduler：插件、队列与算法（/metrics）

指标	类型	标签
`scheduler_goroutines`	Gauge	operation
`scheduler_permit_wait_duration_seconds`	Histogram	result
`scheduler_plugin_evaluation_total`	Counter	extension_point, plugin, profile
`scheduler_plugin_execution_duration_seconds`	Histogram	extension_point, plugin, status
`scheduler_pod_scheduling_sli_duration_seconds`	Histogram	attempts
`scheduler_scheduling_algorithm_duration_seconds`	Histogram	（无）
`scheduler_unschedulable_pods`	Gauge	plugin, profile

ServiceAccount 令牌（kube-apiserver）

指标	类型	标签
`serviceaccount_legacy_tokens_total`	Counter	（无）
`serviceaccount_stale_tokens_total`	Counter	（无）
`serviceaccount_valid_tokens_total`	Counter	（无）

全部核心组件共享（BETA）：元信息与 workqueue

指标	类型	标签	说明
`kubernetes_build_info`	Gauge	build_date, compiler, git_commit, git_tree_state, git_version, go_version, major, minor, platform	恒为 1 的版本信息指标，常用于 `kube_build_info` 式版本上报
`kubernetes_feature_enabled`	Gauge	name, stage	记录某个 k8s 特性开关所处阶段与启用状态
`disabled_metrics_total`	Counter	（无）	被禁用指标的数量
`hidden_metrics_total`	Counter	（无）	被隐藏指标的数量
`registered_metrics_total`	Counter	deprecated_version, stability_level	已注册指标总数，按稳定性级别与废弃版本拆分
`running_managed_controllers`	Gauge	manager, name	指示某控制器实例当前在哪个 manager 中运行
`workqueue_adds_total`	Counter	name	workqueue 累计入队次数
`workqueue_depth`	Gauge	name	workqueue 当前队列深度（背压最直观的指标）
`workqueue_longest_running_processor_seconds`	Gauge	name	workqueue 中运行最久的处理协程已运行秒数
`workqueue_queue_duration_seconds`	Histogram	name	条目在队列中等待被取出的时长
`workqueue_retries_total`	Counter	name	workqueue 累计重试次数
`workqueue_unfinished_work_seconds`	Gauge	name	正在进行且尚未被 work_duration 观测到的工作秒数；持续偏大说明存在卡死的线程
`workqueue_work_duration_seconds`	Histogram	name	处理单个 workqueue 条目耗时

说明：workqueue_*、kubernetes_* 与 *_metrics_total 等来自 staging/src/k8s.io/component-base/（sharedPaths）的通用指标，文档中会同时归属到 cloud-controller-manager、kube-apiserver、kube-controller-manager、kube-proxy、kube-scheduler、kubelet 六个核心组件，因为它们在每个组件的 /metrics 上都存在。

八、ALPHA 指标（525 条）：无契约承诺的观测面

Alpha 指标体量最大（525 条），涵盖大量细粒度、低层级的观测点。文档反复强调其无任何 API 保证，可能随时被移除或变更，因此只建议用于短期诊断，不建议沉淀为跨版本长期告警。按文档中 Alpha 一节的排列，其覆盖主题可大致归纳为（以下均为文档中实际列出的指标族前缀）：

aggregator 与 API 发现：aggregator_discovery_aggregation_count_total、aggregator_discovery_nopeer_requests_total、aggregator_discovery_peer_aggregated_cache_hits_total / _misses_total、aggregator_openapi_v2_regeneration_count / _duration、aggregator_unavailable_apiservice / aggregator_unavailable_apiservice_total——监控聚合 API 发现（discovery）的缓存命中、OpenAPI v2 重建与不可用 APIService；
apiextensions-apiserver：apiextensions_apiserver_validation_ratcheting_seconds、apiextensions_openapi_v2_regeneration_count、apiextensions_openapi_v3_regeneration_count——CRD 校验棘轮（validation ratcheting）耗时与 OpenAPI v2/v3 重建计数；
Admission 细粒度观测：apiserver_admission_match_condition_evaluation_errors_total / _seconds / _exclusions_total、apiserver_admission_step_admission_duration_seconds_summary、apiserver_admission_webhook_fail_open_count / _rejection_count / request_total——其中 webhook 相关计数器会记录调用/内部错误类型、拒绝码（大于 600 的码被截断为 600 以约束基数）；
审计：apiserver_audit_error_total / event_total / level_total / requests_rejected_total——审计事件生成、发送、失败与因审计后端错误而拒绝请求的情况；
认证与授权：apiserver_authentication_config_controller_last_config_info、apiserver_authentication_jwt_authenticator_jwks_fetch_last_key_set_info / _last_timestamp_seconds / _latency_seconds、apiserver_authorization_config_controller_last_config_info、apiserver_authorization_decisions_total、apiserver_authorization_match_condition_evaluation_*、apiserver_authorization_webhook_duration_seconds / evaluations_total / evaluations_fail_open_total——JWKS 拉取与配置热加载、授权 webhook 往返、失败放行（fail-open）等细粒度信号；
Watch 缓存与 LIST：apiserver_cache_list_fetched_objects_total、apiserver_cache_list_returned_objects_total——从 watch cache 读取/返回的对象数（两者均已标注自 1.37.0 废弃，观察其去向可判断存储层演进）。

由于 Alpha 数量众多，本文不逐条复述；完整、权威的逐条字段（含 help、标签、端点与废弃版本）请直接查阅仓库中的生成源文档 hack/tools/instrumentation/documentation/documentation.md 的 Alpha 一节，或浏览其配套清单 hack/tools/instrumentation/documentation/documentation-list.yaml。

九、选型建议与注意事项

综合以上分级与字段结构，实践中有几条可以落地的判断准则：

长期告警与公开仪表盘优先用 STABLE：只有 STABLE 保证“终身不增删标签”，如 apiserver_request_total、apiserver_request_duration_seconds、workqueue_depth（BETA）、scheduler_pending_pods、kubelet 资源系列等。注意 STABLE 中也有废弃项（如 apiserver_storage_objects 自 1.34.0 废弃），接入前应核对 Deprecated Versions 字段并优先选用替代项；
BETA 可谨慎使用但要容忍标签增补：例如 kubernetes_feature_enabled、running_managed_controllers、workqueue_* 这类指标非常实用，但需做好“未来新增维度标签”的心理与配置准备；
ALPHA 只用于排障窗口：抓取后短期对比、定位问题可以；写入长期 SLO 前务必先确认其演进状态；
端点信息很重要：同是 kubelet，/metrics、/metrics/resource、/metrics/probes、/metrics/slis 语义不同。配置 Prometheus 抓取任务时要按目标指标核对文档 “Components” 字段给出的端点，避免抓错端口或路径；
一切以生成清单为准：本文与参考文档均以仓库当前 v1.37 版本为准。若你关注的指标在别的版本有增删，应以对应版本的生成产物（或重新运行 hack/tools/instrumentation/update-documentation.sh 的产物）核对。