企业官网建设流程全解析

CubeSandbox 沙箱资源指标完全指南：从 Cubelet 采集原理到 Prometheus 监控实战

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox

CubeSandbox 为每个运行中的 Cube 沙箱提供独立的 CPU 与内存资源指标，由宿主机上的 Cubelet 通过独立的采集链路读取沙箱 cgroup 数据，并通过http://<cubelet-node>:9998/v1/metrics/resource端点以 Prometheus 文本格式导出。本文围绕 docs/zh/guide/resource-metrics.md 展开，完整覆盖指标端点的使用前提、host_sandbox与guest_workload两种统计视角的选择、Cubelet 插件配置、Prometheus 抓取配置、全部基础指标族、可直接上手的 PromQL 查询示例，以及统计周期（metrics epoch）生命周期语义与故障排查方法，帮助你为 AI Agent 沙箱搭建一套基于真实 cgroup 记账的节点级与工作负载级资源观测体系。

概览：指标端点与采集链路

Cubelet 为运行中的 Cube 沙箱提供 CPU 和内存指标，一键安装默认启用该功能，指标端点为：

http://<cubelet-node>:9998/v1/metrics/resource

该端点与 Cubelet 通用指标端点/v1/metrics相互独立。现有的 containerd cgroup monitor 仍保持启用，并可继续通过/v1/metrics导出通用container_*指标；Cube 原生沙箱指标则由独立链路采集，并通过/v1/metrics/resource导出。

在服务端实现上，Cubelet/services/server/server.go 的serveMetrics方法将/v1/metrics/resource注册到独立的 HTTP handler 映射中，并通过appendHttpHandlers拒绝重复路径，避免两个插件静默遮蔽同一端点。

Cubelet 在后台定期采集所选统计视角的资源数据，并将最新结果缓存在内存中。Prometheus 抓取时只读取缓存，不会在 HTTP 请求过程中同步访问所有沙箱。因此，抓取请求不会额外触发与沙箱数量成比例的运行时 RPC；但响应体大小和序列化开销仍会随时间序列数量增长。

网络访问警告Cubelet 的 HTTP 服务本身不提供鉴权或 TLS。

仅应在可信的管理网络中开放9998端口，或通过防火墙、安全组等方式限制访问来源。详见 网络加固。

使用前提

在启用沙箱资源指标前，需要确认以下前提条件：

• 仅面向运行中的沙箱：资源指标只对运行中的 Cube 沙箱生效。沙箱暂停、终止或删除后，对应指标会停止导出。
• 单容器沙箱模型：当前版本面向单容器沙箱，主工作负载使用container_id == sandbox_id。暂不提供多容器级别的资源拆分。
• guest_workload的能力要求：该视角要求沙箱内的cube-agent支持资源指标能力版本1，并使用 cgroup v2 统一层级。
• host_sandbox兼容性更广：该视角只依赖宿主机上的沙箱 cgroup，兼容范围更广，也是默认采集和导出的统计视角。

资源统计视角

资源指标提供两个彼此独立的统计视角：

如何选择：

• 只需要节点侧基础观测时，使用默认的host_sandbox。
• 需要判断沙箱内工作负载的资源使用率或内存压力时，使用guest_workload。
• 需要对比工作负载与运行时开销时，使用all。

两组指标来自不同的资源记账范围，不应直接相加为一个通用总量。host_sandbox的内存值是宿主机 cgroup 的记账值，会受到共享快照页和写时复制（COW）的影响，并不等同于沙箱内看到的逻辑工作集或按比例分摊的物理内存。由于 VMM 开销、共享页和私有 COW 页等因素，host_sandbox与guest_workload的内存值通常不会相等。

工作原理

所有采集都由宿主机上的 Cubelet 主动发起，沙箱不会主动向宿主机推送指标。从插件源码看，resourcemetrics/plugin.go 注册了io.cubelet.internal.v1.resource-metrics内部插件，插件启动时根据export_scopes决定创建哪些采集器：GuestWorkloadSampler通过 containerd 的 Sandbox Controller 获取任务统计，HostSandboxSampler则通过 cgroup 插件读取宿主机 cgroup 快照。两个采集器各自独立运行，互不依赖。

host_sandbox

Cubelet 直接读取宿主机上的沙箱 cgroup。该视角不依赖模板中的cube-agent版本，也不涉及沙箱内的统计周期。宿主机侧指标继续使用节点自身的 cgroup 层级，并保留项目现有的 cgroup v1 和 cgroup v2 兼容逻辑。

在 host_sandbox_sampler.go 中，采集器为每个沙箱维护“分配基线”（assignment baseline）：新沙箱被分配到可复用的宿主机 cgroup 池槽位时，Cubelet 会在挂载沙箱进程前读取并持久化本次分配的计数器基线；每次采样时以当前原始值 - 基线值归一化后写入缓存。这保证了累计指标只包含当前沙箱占用该 cgroup 期间的使用量，不继承同一槽位中上一个沙箱的历史。

guest_workload

Cubelet 通过 containerdTask.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 统一层级。运行时，CubeShim 还会校验StatsContainer返回的资源指标能力版本，避免将旧版本的guest_workload数据识别为有效指标。

在 guest_workload.go 中，DecodeGuestWorkloadMetric会校验指标类型是否为io.containerd.cgroups.v1.Metrics、metric ID 是否与容器 ID 匹配，并校验时间戳有效性，随后解析出 CPU 使用、CPU 限流和内存使用等原始字段。采样到的原始计数会与当前统计周期（epoch）的基线做差值运算（subtractGuestCounters），得到归一化后的累计值。

旧模板中的cube-agent可能不支持上述能力。这类沙箱不会导出guest_workload，但仍可导出host_sandbox。

Cubelet 配置

通过一键安装部署后，Cubelet 配置文件位于：

/usr/local/services/cubetoolbox/Cubelet/config/config.toml

资源指标插件的默认配置如下（与仓库中 Cubelet/config/config.toml 及插件内defaultConfig()保持一致）：

[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"]

配置项说明

从源码看，这些配置项会通过插件初始化逻辑映射到采集器的内部参数：request_timeout用于构造带超时的采集上下文，max_concurrent_requests决定采集器内部的信号量容量（并发上限），stale_after与collection_interval会在配置校验时被检查（validate()要求StaleAfter >= CollectionInterval，且各项均为正值），校验失败会直接导致 Cubelet 启动失败。

发生短暂采集失败时，Cubelet 会继续导出最近一次成功样本。只有样本年龄超过stale_after后，对应统计视角才会停止导出。该行为在采样器的Latest/ListLatest方法中实现：当样本年龄超过stale_after时，可用性状态会从available切换为stale，从而停止导出。

配置校验失败会导致 Cubelet 启动失败，例如：

• stale_after小于collection_interval；
• export_scopes包含不支持的值。

修改配置后，重启 Cubelet：

sudo systemctl restart cube-sandbox-cubelet.service

Prometheus 抓取配置

建议为沙箱资源指标配置独立的抓取任务：

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.go 中由maxConcurrentPrometheusScrapes = 2常量配合promhttp.HandlerOpts{MaxRequestsInFlight: ...}实现。正常的单个 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时：

1. 将export_scopes设置为["guest_workload"]或["all"]；
2. 重启 Cubelet；
3. 确认沙箱内的cube-agent兼容资源指标能力版本1。

端点返回 HTTP 200 但响应体为空不一定表示故障。以下情况都会产生空结果：

• 节点上没有运行中的沙箱；
• 插件已禁用；
• Cubelet 尚未完成首次采样。

基础指标族

Cubelet 仅导出 Counter 和 Gauge 类型的基础指标。CPU 使用核数以及 CPU、内存使用率等派生值由 Prometheus 查询计算。

CPU 和内存上限仅在 cgroup 配置了有限值时导出。未配置上限时，不会使用0或某个极大值代替。当前内存用量不受此限制，只要对应统计视角可用就会导出。在导出实现中，host_sandbox的 CPU 上限由quota/period计算得出，仅在CPULimitUnlimited == false且 period 大于 0 时导出；内存上限也仅在非 unlimited 时导出。

host_sandbox指标

host_sandbox指标仅包含sandbox_id标签。

累计指标只包含当前沙箱占用宿主机 cgroup 期间的使用量，不包含可复用 cgroup 槽位中上一个沙箱的历史。

guest_workload指标

guest_workload指标包含以下标签：

• sandbox_id
• container_id

累计指标以当前统计周期（metrics epoch）为窗口，不包含模板、克隆或回滚继承的历史。统计周期的生命周期语义见后文。

需要说明的是，尽管cgroup1stats在代码中承担解码任务，guest_workload的数据源是沙箱内核 cgroup v2 统一层级下的工作负载 cgroup，指标值由cube-agent StatsContainer返回，二者并不冲突。

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状态建立一个统计周期，并将首次成功采样作为基线：

导出的累计值 = 当前原始值 - 当前统计周期基线

这样可以排除继承的历史，并将回滚后的数据表示为新的统计窗口。当前内存用量是瞬时值，不进行基线扣减。

从源码看，统计周期（epoch）由 Cubelet/pkg/store/cubebox/guest_metrics_epoch.go 中的GuestMetricsEpoch结构持久化，包含prepared、pending、ready、degraded四种状态以及fresh_create、rollback两种创建原因。基线快照记录 epoch 开始时刻的累计计数器，采样时以“原始值减基线”得到该窗口内的增量。GuestWorkloadSampler会通过InvalidateEpoch在检测到 epoch 变化时重建窗口，并将生命周期事件（暂停、回滚等）映射为采样不可用状态（guestWorkloadSamplingUnavailable在暂停/终止/回滚时返回 true）。

guest_workload生命周期

如果生命周期元数据发生瞬时故障，导致运行中的沙箱暂时没有持久化 fresh 统计周期，guest_workload采集器会先重新建立并持久化 pending 统计周期，再继续采集。恢复失败时仍保持不可用，并在后续采集周期重试。

Prometheus 不理解 Cubelet 的统计周期语义。只有累计值实际下降时，rate()和increase()才会按照计数器重置处理。需要可靠识别回滚或新统计窗口时，应查询：

• cubesandbox_guest_workload_metrics_epoch
• cubesandbox_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.StatsRPC 和宿主机 cgroup 的读取频率，Prometheus 的scrape_interval控制 HTTP 抓取和样本写入频率。节点沙箱较多或 Prometheus 每几分钟才抓取一次时，可以适当增大collection_interval，并同步增大stale_after。

资源端点只保存最新样本，不保存历史；发生在两次 Prometheus 抓取之间的短时内存峰值不会被保留。CPU 速率查询窗口内应包含多个成功写入 Prometheus 的样本。

两个间隔都不会减少活跃时间序列数量。显式设置export_scopes = ["all"]时，单容器沙箱最多导出 22 条时间序列；如需减少序列数量，应调整export_scopes或使用 Prometheusmetric_relabel_configs。

补充一点源码层面的实现细节：当节点沙箱数量超过max_concurrent_requests时，采集器会按批次调度，batchDispatchInterval将collection_interval平均切分到多个批次，并在每次调度间隔上叠加约 ±10% 的随机抖动（jitter），以平滑并发读取压力，避免所有沙箱在同一瞬间被打满并发上限。

升级旧模板和快照

快照模板会捕获沙箱内的进程和内存状态。仅升级节点上的 Cubelet、CubeShim 或沙箱虚拟机镜像文件，不会替换旧模板内存快照中的cube-agent。

旧模板中的cube-agent可能不具备本版本要求的 cgroup v2 统计语义，也不会声明资源指标能力版本1。这类沙箱不会导出guest_workload，但仍可导出host_sandbox。

镜像构建模板

对于通过镜像构建的模板，需要执行模板redo。redo会使用节点当前的沙箱虚拟机镜像和cube-agent，为同一个模板 ID 重新制作副本。任务完成后，新创建的沙箱即可导出guest_workload指标。

节点升级后，Dashboard 里标了「需重建」的模板要先点「重建模板」，再建沙箱。其它模板可以继续直接创建（会按模板记录的版本在节点本地查找，或从组件仓库下载）。只有当你需要当前节点上的 guest image /cube-agent、以便新沙箱导出guest_workload指标时，才需要对已可用的模板再点一次「重建模板」。

用户快照和已有沙箱

• 对于从运行中沙箱创建的用户快照，应先使用兼容的新模板创建沙箱，再重新创建快照。
• 已经运行或暂停的旧沙箱仍保留内存中的旧cube-agent，需要删除并重新创建才能完成升级。

一键安装包会将经过审核的cube-agent写入沙箱虚拟机镜像。只要模板是READY且没有标「需重建」，升级后仍可直接创建沙箱。

运行时，CubeShim 还会校验StatsContainer返回的资源指标能力版本，避免将旧版本的guest_workload数据识别为有效指标。

故障排查

Cubelet 启动失败时，先查看 systemd 日志；服务已运行但采集异常时，查看 Cubelet 业务日志：

sudo journalctl -u cube-sandbox-cubelet.service -n 200 --no-pager sudo tail -200 /data/log/Cubelet/Cubelet-req.log

延伸阅读

• 指标采集与导出完整实现：Cubelet/plugins/cube/internals/resourcemetrics/（包含插件注册、两个采样器、Prometheus 导出器及配套单元测试）
• 统计周期持久化模型：Cubelet/pkg/store/cubebox/guest_metrics_epoch.go
• 端点注册逻辑：Cubelet/services/server/server.go
• 一键安装默认配置：Cubelet/config/config.toml
• 网络加固建议：docs/zh/guide/network-hardening.md

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox