沙箱资源指标
Cubelet 为运行中的 Cube 沙箱提供 CPU 和内存指标。一键安装默认启用该功能，指标端点为：
http://<cubelet-node>:9998/v1/metrics/resource该端点与 Cubelet 通用指标端点 /v1/metrics 相互独立。现有的 containerd cgroup monitor 仍保持启用，并可继续通过 /v1/metrics 导出通用 container_* 指标；本文介绍的 Cube 原生沙箱指标由独立链路采集，并通过 /v1/metrics/resource 导出。
Cubelet 在后台定期采集所选统计视角的资源数据，并将最新结果缓存在内存中。Prometheus 抓取时只读取缓存，不会在 HTTP 请求过程中同步访问所有沙箱。因此，抓取请求不会额外触发与沙箱数量成比例的运行时 RPC；但响应体大小和序列化开销仍会随时间序列数量增长。
使用前提
- 资源指标仅面向运行中的 Cube 沙箱。沙箱暂停、终止或删除后，对应指标会停止导出。
- 当前版本面向单容器沙箱，主工作负载使用
container_id == sandbox_id。暂不提供多容器级别的资源拆分。 guest_workload要求沙箱内的cube-agent支持资源指标能力版本1，并使用 cgroup v2 统一层级。host_sandbox只依赖宿主机上的沙箱 cgroup，兼容范围更广，也是默认采集和导出的统计视角。
资源统计视角
资源指标提供两个彼此独立的统计视角：
| 统计视角 | 统计范围 | 适用场景 |
|---|---|---|
host_sandbox | 宿主机内核统计的沙箱 cgroup，包含 CubeShim、VMM 及其他宿主机侧资源占用。 | 宿主机侧沙箱资源记账和基础运维观测。 |
guest_workload | 沙箱内核统计的工作负载容器 cgroup，不包含 cube-agent 等沙箱管理进程。 | 用户代码的 CPU、内存使用率和内存限制观测。 |
all | 同时导出以上两组指标。 | 同时分析工作负载使用量和运行时开销。 |
如何选择
- 只需要节点侧基础观测时，使用默认的
host_sandbox。 - 需要判断沙箱内工作负载的资源使用率或内存压力时，使用
guest_workload。 - 需要对比工作负载与运行时开销时，使用
all。
两组指标来自不同的资源记账范围，不应直接相加为一个通用总量。
host_sandbox 的内存值是宿主机 cgroup 的记账值，会受到共享快照页和写时复制（COW）的影响，并不等同于沙箱内看到的逻辑工作集或按比例分摊的物理内存。由于 VMM 开销、共享页和私有 COW 页等因素，host_sandbox 与 guest_workload 的内存值通常不会相等。
工作原理
所有采集都由宿主机上的 Cubelet 主动发起，沙箱不会主动向宿主机推送指标。
host_sandbox
Cubelet 直接读取宿主机上的沙箱 cgroup。该视角不依赖模板中的 cube-agent 版本，也不涉及沙箱内的统计周期。
宿主机侧指标继续使用节点自身的 cgroup 层级，并保留项目现有的 cgroup v1 和 cgroup v2 兼容逻辑。
guest_workload
Cubelet 通过 containerd Task.Stats 调用 CubeShim，再由 CubeShim 调用沙箱内的 cube-agent StatsContainer，读取工作负载容器 cgroup。
该视角依赖以下能力：
- 沙箱内启用 cgroup v2 统一层级；
cube-agent声明资源指标能力版本1；- CubeShim 能够通过
Task.Stats返回完整的工作负载统计； - Cubelet 能够根据沙箱生命周期维护统计周期和计数器基线。
CubeShim 会在启动沙箱时通过 agent.unified_cgroup_hierarchy=true 为 cube-agent 启用 cgroup v2 统一层级。
旧模板中的 cube-agent 可能不支持上述能力。这类沙箱不会导出 guest_workload，但仍可导出 host_sandbox。
Cubelet 配置
通过一键安装部署后，Cubelet 配置文件位于：
/usr/local/services/cubetoolbox/Cubelet/config/config.toml资源指标插件的默认配置如下：
[plugins."io.cubelet.internal.v1.resource-metrics"]
enabled = true
collection_interval = "5s"
request_timeout = "2s"
max_concurrent_requests = 8
stale_after = "15s"
export_scopes = ["host_sandbox"]配置项说明
| 配置项 | 说明 |
|---|---|
enabled | 是否启动资源指标采集，默认启用。设置为 false 后，端点仍返回 HTTP 200，但不会导出沙箱资源指标。 |
collection_interval | Cubelet 更新内存缓存的目标间隔。该配置决定 Task.Stats RPC 和宿主机 cgroup 的读取频率，与 Prometheus 抓取间隔相互独立。 |
request_timeout | 单次 Task.Stats 请求或宿主机 cgroup 读取的超时时间。 |
max_concurrent_requests | 单个采集器的最大并发请求数。guest_workload 和 host_sandbox 分别使用该上限，两者的并发上限相互独立。 |
stale_after | 最近一次成功样本超过该时长后，停止导出对应统计视角。该值不得小于 collection_interval，并应为调度和短暂采集失败预留余量。 |
export_scopes | 控制采集和导出的统计视角。可设置为 ["host_sandbox"]、["guest_workload"] 或 ["all"]，默认值为 ["host_sandbox"]。未选中的采集器不会启动；["all"] 会启动两个采集器。 |
发生短暂采集失败时，Cubelet 会继续导出最近一次成功样本。只有样本年龄超过 stale_after 后，对应统计视角才会停止导出。
配置校验失败会导致 Cubelet 启动失败，例如：
stale_after小于collection_interval；export_scopes包含不支持的值。
修改配置后，重启 Cubelet：
sudo systemctl restart cube-sandbox-cubelet.servicePrometheus 抓取配置
建议为沙箱资源指标配置独立的抓取任务：
scrape_configs:
- job_name: cubesandbox-resource
scrape_interval: 30s
scrape_timeout: 10s
metrics_path: /v1/metrics/resource
static_configs:
- targets:
- <compute-node-ip>:9998将目标地址替换为各 Cubelet 节点在可信管理网络中的地址。
使用独立抓取任务后，可以单独调整资源指标的抓取间隔、超时时间和 metric_relabel_configs，而不会影响 Cubelet 通用指标。
资源指标端点最多同时处理两个抓取请求。超过该上限的请求会返回 HTTP 503，以避免多个大响应同时占用 Cubelet 的 CPU 和内存。正常的单个 Prometheus 抓取任务不会触发该限制；如果出现 503，应检查是否有多个 Prometheus 实例或手工请求同时抓取同一节点。
验证指标端点
先确认 Cubelet 正常运行，并且节点上至少有一个状态为 Up 的沙箱：
sudo systemctl is-active cube-sandbox-cubelet.service
/usr/local/services/cubetoolbox/Cubelet/bin/cubecli cubebox ls -a --no-trunc等待至少一个采集周期后，在 Cubelet 节点上执行：
curl -fsS http://127.0.0.1:9998/v1/metrics/resource | \
grep '^cubesandbox_'默认配置会导出 cubesandbox_host_sandbox_* 指标。
需要导出 guest_workload 时：
- 将
export_scopes设置为["guest_workload"]或["all"]； - 重启 Cubelet；
- 确认沙箱内的
cube-agent兼容资源指标能力版本1。
端点返回 HTTP 200 但响应体为空不一定表示故障。以下情况都会产生空结果：
- 节点上没有运行中的沙箱；
- 插件已禁用；
- Cubelet 尚未完成首次采样。
基础指标族
Cubelet 仅导出 Counter 和 Gauge 类型的基础指标。CPU 使用核数以及 CPU、内存使用率等派生值由 Prometheus 查询计算。
CPU 和内存上限仅在 cgroup 配置了有限值时导出。未配置上限时，不会使用 0 或某个极大值代替。当前内存用量不受此限制，只要对应统计视角可用就会导出。
host_sandbox 指标
host_sandbox 指标仅包含 sandbox_id 标签。
累计指标只包含当前沙箱占用宿主机 cgroup 期间的使用量，不包含可复用 cgroup 槽位中上一个沙箱的历史。
| 指标 | 类型 | 单位与说明 |
|---|---|---|
cubesandbox_host_sandbox_cpu_usage_seconds_total | Counter | 沙箱在宿主机上累计使用的 CPU 秒数。 |
cubesandbox_host_sandbox_cpu_user_seconds_total | Counter | 累计使用的用户态 CPU 秒数。 |
cubesandbox_host_sandbox_cpu_system_seconds_total | Counter | 累计使用的内核态 CPU 秒数。 |
cubesandbox_host_sandbox_cpu_throttled_seconds_total | Counter | 累计受到 CPU 限流的秒数。 |
cubesandbox_host_sandbox_cpu_periods_total | Counter | 累计 CPU 调度周期数。 |
cubesandbox_host_sandbox_cpu_throttled_periods_total | Counter | 累计发生限流的 CPU 调度周期数。 |
cubesandbox_host_sandbox_cpu_limit_cores | Gauge | 宿主机沙箱 cgroup 的有限 CPU 上限，单位为 CPU 核数。 |
cubesandbox_host_sandbox_memory_current_bytes | Gauge | 当前计入宿主机沙箱 cgroup 的内存字节数。 |
cubesandbox_host_sandbox_memory_limit_bytes | Gauge | 宿主机沙箱 cgroup 的有限内存上限，单位为字节。 |
cubesandbox_host_sandbox_memory_failures_total | Counter | 当前沙箱占用该 cgroup 期间发生的内存限制失败次数。 |
guest_workload 指标
guest_workload 指标包含以下标签：
sandbox_idcontainer_id
累计指标以当前统计周期（metrics epoch）为窗口，不包含模板、克隆或回滚继承的历史。统计周期的生命周期语义见后文。
| 指标 | 类型 | 单位与说明 |
|---|---|---|
cubesandbox_guest_workload_cpu_usage_seconds_total | Counter | 累计使用的 CPU 秒数。 |
cubesandbox_guest_workload_cpu_user_seconds_total | Counter | 累计使用的用户态 CPU 秒数。 |
cubesandbox_guest_workload_cpu_system_seconds_total | Counter | 累计使用的内核态 CPU 秒数。 |
cubesandbox_guest_workload_cpu_throttled_seconds_total | Counter | 累计受到 CPU 限流的秒数。 |
cubesandbox_guest_workload_cpu_periods_total | Counter | 累计 CPU 调度周期数。 |
cubesandbox_guest_workload_cpu_throttled_periods_total | Counter | 累计发生限流的 CPU 调度周期数。 |
cubesandbox_guest_workload_cpu_limit_cores | Gauge | 配置的有限 CPU 上限，单位为 CPU 核数。 |
cubesandbox_guest_workload_memory_current_bytes | Gauge | 当前计入工作负载 cgroup 的内存字节数。 |
cubesandbox_guest_workload_memory_limit_bytes | Gauge | 配置的有限内存上限，单位为字节。 |
cubesandbox_guest_workload_memory_failures_total | Counter | 当前统计周期内发生的内存限制失败次数。 |
cubesandbox_guest_workload_metrics_epoch | Gauge | 当前统计周期的序号。 |
cubesandbox_guest_workload_metrics_epoch_start_time_seconds | Gauge | 当前统计周期的开始时间，使用 Unix 时间戳秒数表示。 |
PromQL 示例
宿主机侧 CPU 使用核数
以下查询返回沙箱在宿主机侧平均使用的 CPU 核数，其中包含 VMM 和 CubeShim 等运行时开销：
rate(cubesandbox_host_sandbox_cpu_usage_seconds_total[5m])宿主机侧 CPU 使用率
以下查询以宿主机沙箱 cgroup 配置的有限 CPU 上限为分母计算使用率：
100 *
rate(cubesandbox_host_sandbox_cpu_usage_seconds_total[5m])
/
cubesandbox_host_sandbox_cpu_limit_cores如果未配置有限 CPU 上限，仍可查询实际使用的 CPU 核数，但无法计算具有明确分母的 CPU 使用率。
宿主机侧内存记账值
cubesandbox_host_sandbox_memory_current_bytes该值适合观察宿主机 cgroup 当前记到沙箱上的内存，不应解释为沙箱内的逻辑工作集。
共享快照页可能使该值低于 guest_workload 的当前内存值；VMM、CubeShim 和私有 COW 页等宿主机侧开销也可能使该值更高。
宿主机侧内存使用率
100 *
cubesandbox_host_sandbox_memory_current_bytes
/
cubesandbox_host_sandbox_memory_limit_bytes当宿主机沙箱 cgroup 未设置有限内存上限时，Cubelet 不会导出 cubesandbox_host_sandbox_memory_limit_bytes，因此无法计算基于上限的内存使用率。
工作负载 CPU 使用核数
以下查询返回工作负载在指定时间窗口内平均使用的 CPU 核数：
rate(cubesandbox_guest_workload_cpu_usage_seconds_total[5m])例如，查询结果为 0.5，表示该工作负载在查询窗口内平均使用了约半个 CPU 核。
工作负载 CPU 使用率
以下查询以工作负载配置的有限 CPU 上限为分母计算使用率：
100 *
rate(cubesandbox_guest_workload_cpu_usage_seconds_total[5m])
/
cubesandbox_guest_workload_cpu_limit_cores如果工作负载未配置有限 CPU 上限，仍可查询实际使用的 CPU 核数，但无法计算具有明确分母的 CPU 使用率。
工作负载内存使用率
100 *
cubesandbox_guest_workload_memory_current_bytes
/
cubesandbox_guest_workload_memory_limit_bytes当工作负载未设置有限内存上限时，Cubelet 不会导出 cubesandbox_guest_workload_memory_limit_bytes，因此无法计算基于上限的内存使用率。
内存限制失败次数
以下查询返回最近 5 分钟内发生的内存限制失败次数：
increase(cubesandbox_guest_workload_memory_failures_total[5m])识别统计周期变化
以下查询返回最近 5 分钟内已有时间序列的统计周期变化次数，可用于标记回滚等统计窗口切换：
changes(cubesandbox_guest_workload_metrics_epoch[5m])生命周期语义
本节主要说明 guest_workload 的统计周期，以及两种视角在暂停、回滚和删除等操作中的行为。
为什么需要统计周期
CPU 使用时间和内存限制失败次数来自 cgroup 累计计数器。制作模板或快照时，这些计数器会随沙箱状态一起保存。从模板或快照创建新沙箱时会继承已有计数；执行回滚时，原始计数器还可能退回到快照时的值。
如果直接按照 sandbox_id 导出原始计数：
- 模板制作阶段产生的 CPU 和内存限制失败历史会被计入新沙箱；
- 回滚后，同一指标可能出现无法区分原因的数值倒退。
为解决这些问题，Cubelet 会为每个新的 guest_workload 状态建立一个统计周期，并将首次成功采样作为基线：
导出的累计值 = 当前原始值 - 当前统计周期基线这样可以排除继承的历史，并将回滚后的数据表示为新的统计窗口。当前内存用量是瞬时值，不进行基线扣减。
guest_workload 生命周期
| 生命周期事件 | 指标行为 |
|---|---|
| 新建沙箱、从模板或快照创建、克隆、重建工作负载 | 创建新的统计周期，并使用首次成功采样排除继承的累计历史。 |
| 创建快照或提交模板 | 保持当前统计周期。 |
| 回滚 | 回滚期间停止导出；完成后创建新的统计周期，累计指标重新从 0 开始。如果运行时恢复请求发出后失败，新统计周期会保持准备状态，guest_workload 将继续不可用，直到后续回滚成功，或删除并重建沙箱。 |
| 暂停 | 保持当前统计周期，但停止导出指标，而不是导出 0。 |
| 恢复运行 | 继续暂停前的统计周期。 |
| 删除 | 删除缓存和对应指标序列。 |
| Cubelet 重启 | 从持久化状态恢复统计周期和基线，不重新计算已有窗口。 |
如果生命周期元数据发生瞬时故障，导致运行中的沙箱暂时没有持久化 fresh 统计周期，guest_workload 采集器会先重新建立并持久化 pending 统计周期，再继续采集。恢复失败时仍保持不可用，并在后续采集周期重试。
Prometheus 不理解 Cubelet 的统计周期语义。只有累计值实际下降时，rate() 和 increase() 才会按照计数器重置处理。
需要可靠识别回滚或新统计窗口时，应查询：
cubesandbox_guest_workload_metrics_epochcubesandbox_guest_workload_metrics_epoch_start_time_seconds
当前版本不导出按统计周期精确计算的内存峰值。内存当前值仍表示采样时刻的实际点值。
host_sandbox 生命周期
host_sandbox 不使用 guest_workload 的统计周期，而是按照宿主机 cgroup 的分配关系统计：
- 新沙箱被分配到可复用的宿主机 cgroup 池槽位时，Cubelet 会在挂载沙箱进程前读取并持久化本次分配的基线。
- 升级 Cubelet 时已经存在的沙箱可能没有该持久化字段；Cubelet 会在升级后的首次成功采样中建立兼容基线。
- Cubelet 会在挂载沙箱进程前重试瞬时的分配计数器读取失败。如果多次尝试仍失败，沙箱仍会正常创建，但该沙箱的
host_sandbox会保持不可用，不会导出缺失初始使用量的累计窗口。修复持续存在的宿主机 cgroup 读取问题后，需要重新创建沙箱。 - 新沙箱不会继承同一槽位中上一个沙箱的 CPU 或内存限制失败历史。
- 创建快照和执行回滚不会重置基线，因为这两类操作不会更换宿主机上的沙箱进程，也不会改变对应的 cgroup 分配关系。
- 暂停时停止导出，恢复运行后继续此前的累计值。
- 删除沙箱后，移除对应的指标序列。
采集与抓取调优
collection_interval 控制 Task.Stats RPC 和宿主机 cgroup 的读取频率，Prometheus 的 scrape_interval 控制 HTTP 抓取和样本写入频率。节点沙箱较多或 Prometheus 每几分钟才抓取一次时，可以适当增大 collection_interval，并同步增大 stale_after。
资源端点只保存最新样本，不保存历史；发生在两次 Prometheus 抓取之间的短时内存峰值不会被保留。CPU 速率查询窗口内应包含多个成功写入 Prometheus 的样本。
两个间隔都不会减少活跃时间序列数量。显式设置 export_scopes = ["all"] 时，单容器沙箱最多导出 22 条时间序列；如需减少序列数量，应调整 export_scopes 或使用 Prometheus metric_relabel_configs。
升级旧模板和快照
快照模板会捕获沙箱内的进程和内存状态。仅升级节点上的 Cubelet、CubeShim 或沙箱虚拟机镜像文件，不会替换旧模板内存快照中的 cube-agent。
旧模板中的 cube-agent 可能不具备本版本要求的 cgroup v2 统计语义，也不会声明资源指标能力版本 1。这类沙箱不会导出 guest_workload，但仍可导出 host_sandbox。
镜像构建模板
对于通过镜像构建的模板，需要执行模板 redo。
redo 会使用节点当前的沙箱虚拟机镜像和 cube-agent，为同一个模板 ID 重新制作副本。任务完成并且兼容状态恢复为 OK 后，新创建的沙箱即可导出 guest_workload 指标。
STALE 只表示节点当前 guest/agent 版本与模板记录的版本不一致，不阻止创建。READY 模板仍可用来创建沙箱；创建时会按模板记录的版本在节点本地查找对应组件。如果节点上没有这些版本，创建会失败，需要先把对应组件版本放到多版本目录。
用户快照和已有沙箱
- 对于从运行中沙箱创建的用户快照，应先使用兼容的新模板创建沙箱，再重新创建快照。
- 已经运行或暂停的旧沙箱仍保留内存中的旧
cube-agent，需要删除并重新创建才能完成升级。
一键安装包会将经过审核的 cube-agent 写入沙箱虚拟机镜像，并记录组件版本和校验值。兼容矩阵里的 STALE 只供查看；只要模板是 READY，仍可按模板记录的组件版本创建沙箱。
运行时，CubeShim 还会校验 StatsContainer 返回的资源指标能力版本，避免将旧版本的 guest_workload 数据识别为有效指标。
故障排查
| 现象 | 常见原因与处理方式 |
|---|---|
无法连接 9998 | 确认 cube-sandbox-cubelet.service 正常运行，并检查监听地址、防火墙和安全组。 |
HTTP 200，但没有任何 cubesandbox_* 指标 | 确认插件为 enabled = true，节点上存在状态为 Up 的沙箱，并等待至少一个 collection_interval。暂停的沙箱不会导出指标。 |
配置了 guest_workload，但没有对应指标 | 确认 export_scopes 为 ["guest_workload"] 或 ["all"]。如果配置正确，通常是沙箱内的 cube-agent 未声明资源指标能力版本 1；镜像构建模板可执行 template redo。如果模板兼容但问题仍然存在，检查 Cubelet 业务日志中的 Task.Stats 错误。 |
| 原有指标突然消失 | 沙箱可能已暂停或删除；也可能是连续采集失败后，样本年龄超过了 stale_after。 |
新沙箱没有 host_sandbox 指标 | Cubelet 可能在创建阶段已耗尽宿主机 cgroup 分配基线的读取尝试。检查 Cubelet 日志中的 capture host metrics baseline，修复持续存在的宿主机 cgroup 读取问题后重新创建沙箱。 |
| 抓取返回 HTTP 503 | 同一节点已有两个资源指标抓取正在处理。检查是否存在重复抓取任务或并发手工请求。 |
| CPU 或内存上限指标缺失 | 对应 cgroup 未配置有限上限，这是预期行为；CPU 累计使用量和当前内存用量仍可正常导出。 |
| 指标更新频率不符合预期 | collection_interval 控制 Cubelet 采集频率，Prometheus scrape_interval 控制样本持久化频率，应分别检查两处配置。 |
Cubelet 启动失败时，先查看 systemd 日志；服务已运行但采集异常时，查看 Cubelet 业务日志：
sudo journalctl -u cube-sandbox-cubelet.service -n 200 --no-pager
sudo tail -200 /data/log/Cubelet/Cubelet-req.log