# E2B 沙箱双层资源遥测体系设计分析

## 1. 概述

E2B沙箱平台拥有两套资源监控体系，分别从宿主机内核、虚拟机内部两个视角，监控Firecracker微虚拟机资源使用情况。

宿主机层（HostStats）

核心文件：

orchestrator/internal/sandbox/hoststats_collector.go

orchestrator/internal/sandbox/cgroup/manager.go

观测视角：宿主机内核借助cgroup v2、gopsutil/process工具监控Firecracker进程

导出目标：ClickHouse

虚拟机层（Sandbox Metrics）

核心文件：

envd/internal/host/metrics.go

envd/internal/api/store.go

orchestrator/internal/metrics/sandboxes.go

观测视角：虚拟机内部envd守护进程，上报虚拟机系统资源状态

导出目标：ClickHouse

两套体系作用互补：HostStats用于精准计费、宿主机资源调度；Sandbox Metrics面向用户监控、异常告警、容量评估。

## 2. 宿主机层监控（Host-observed）

### 2.1 核心工作机制

1. 进程原子加入cgroup

创建CgroupHandle时，打开cgroup目录文件句柄与memory.peak文件句柄。启动Firecracker进程时，通过内核能力将进程直接划入指定cgroup，杜绝竞争问题。进程启动完成后，立刻关闭cgroup目录句柄防止资源泄露，保留memory.peak句柄持续读取内存峰值数据。

2. 两层指标合并采集

进程层：使用gopsutil/process读取Firecracker进程的用户态CPU时间、内核态CPU时间、常驻内存、虚拟内存。

内核层：读取cgroup v2文件，获取CPU总耗时、用户态/内核态CPU耗时、当前内存、内存峰值。

数据聚合：HostStatsCollector整合进程层与内核层数据，统一推送至ClickHouse。

### 2.2 采集指标清单（共13项）

#### 沙箱基础元数据

SandboxID：字符串，沙箱唯一编号，来源runtime.SandboxID

SandboxExecutionID：字符串，单次运行实例编号，来源runtime.ExecutionID

SandboxTemplateID：字符串，沙箱模板编号，来源runtime.TemplateID

SandboxBuildID：字符串，构建编号，来源入参buildID

SandboxTeamID：唯一标识，团队/租户编号，来源runtime.TeamID

SandboxVCPUCount：长整型，分配给沙箱的虚拟CPU数量，来源config.Vcpu

SandboxMemoryMB：长整型，分配给沙箱的内存大小（单位MB），来源config.RamMB

Timestamp：时间类型，数据采样时间，来源系统当前时间

#### 进程级指标（读取/proc/进程ID文件）

FirecrackerCPUUserTime：浮点型，单位秒，进程用户态CPU运行时长，对应gopsutil的times.User

FirecrackerCPUSystemTime：浮点型，单位秒，进程内核态CPU运行时长，对应gopsutil的times.System

FirecrackerMemoryRSS：无符号长整型，单位字节，进程常驻内存大小，对应gopsutil的memInfo.RSS

FirecrackerMemoryVMS：无符号长整型，单位字节，进程虚拟内存大小，对应gopsutil的memInfo.VMS

#### cgroup内核级指标（读取/sys/fs/cgroup/e2b/sbx-编号/目录文件）

CgroupCPUUsageUsec：无符号长整型，单位微秒，cgroup内CPU总使用时长，来源cpu.stat文件usage_usec字段

CgroupCPUUserUsec：无符号长整型，单位微秒，cgroup内用户态CPU时长，来源cpu.stat文件user_usec字段

CgroupCPUSystemUsec：无符号长整型，单位微秒，cgroup内内核态CPU时长，来源cpu.stat文件system_usec字段

CgroupMemoryUsage：无符号长整型，单位字节，cgroup当前内存使用量，来源memory.current文件

CgroupMemoryPeak：无符号长整型，单位字节，cgroup运行以来内存使用最大值，来源memory.peak文件

### 2.3 CgroupHandle 完整生命周期

1. 初始化：创建沙箱专属cgroup目录，打开目录句柄、memory.peak句柄，状态变为已创建

2. 句柄持有：对外提供目录句柄，用于启动Firecracker进程

3. 进程启动：内核将进程划入对应cgroup，进程启动完成

4. 释放句柄：关闭cgroup目录句柄，保留memory.peak句柄

5. 循环采集：定时读取进程与cgroup资源数据，持续上报至ClickHouse

6. 停止采集：终止定时任务，完成最后一次数据采样

7. 销毁清理：关闭memory.peak句柄，删除cgroup目录，流程结束

补充说明：cgroup目录句柄仅用于启动进程，用完立即释放；memory.peak句柄全程保留，适配高版本内核内存峰值重置能力。

## 3. 虚拟机层监控（Guest-reported）

### 3.1 虚拟机内envd进程采集指标

envd是运行在Firecracker虚拟机内部的守护进程，负责采集虚拟机系统资源：

Timestamp：长整型，虚拟机内部UTC时间戳，来源系统时间转换

CPUCount：无符号整型，虚拟机识别到的CPU核心数，来源cpu.Counts接口

CPUUsedPercent：浮点型，虚拟机整体CPU使用率（保留2位小数），来源cpu.Percent接口

MemTotalMiB：无符号长整型（已废弃），内存总大小（单位MB），来源内存信息换算

MemUsedMiB：无符号长整型（已废弃），内存已用大小（单位MB），来源内存信息换算

MemTotal：无符号长整型，内存总大小（单位字节，精准数据），来源内存原始数据

MemUsed：无符号长整型，内存已用大小（单位字节，精准数据），来源内存原始数据

DiskTotal：无符号长整型，根分区总容量（单位字节），来源磁盘分区统计接口

DiskUsed：无符号长整型，根分区已用容量（单位字节），来源磁盘分区统计接口计算结果

### 3.2 宿主机Orchestrator处理规则

Orchestrator中的SandboxObserver模块，接收虚拟机上报数据，转换为标准监控指标，配套多项校验与处理逻辑。

#### 版本兼容规则

minEnvdVersionForMetrics：版本≥0.1.5，允许基础指标采集

minEnvVersionForMetricsTimestamp：版本≥0.1.3，开启虚拟机与宿主机时钟校验

minEnvdVersionForMemoryPrecise：版本≥0.2.4，直接使用字节单位内存数据；低版本需将MB换算为字节

minEnvdVersionForDiskMetrics：版本≥0.2.4，开启磁盘指标采集

#### 时钟漂移校验

对比宿主机UTC时间、虚拟机上报时间戳，两者差值超过2秒时，打印警告日志。用于排查虚拟机时间未同步、虚拟化时钟异常问题。

#### 并发请求限制

为避免大量沙箱同时请求拖垮服务，按照沙箱总数除以5计算最大并发数，限制HTTP请求并发量。

#### 资源阈值告警

虚拟机CPU使用率、内存使用率任意一项超过80%，立即打印警告日志。

### 3.3 对外输出监控指标

cpu_total：整型指标，代表虚拟CPU核心数，附带标签：沙箱ID、租户ID

cpu_used：浮点型指标，代表CPU使用率（百分比），附带标签：沙箱ID、租户ID

memory_total：整型指标，代表内存总大小（字节），附带标签：沙箱ID、租户ID

memory_used：整型指标，代表内存已用大小（字节），附带标签：沙箱ID、租户ID

disk_total：整型指标，代表磁盘总大小（字节），附带标签：沙箱ID、租户ID

disk_used：整型指标，代表磁盘已用大小（字节），附带标签：沙箱ID、租户ID

## 4. 两套监控体系对比

采集位置：

HostStats：宿主机Orchestrator服务

Sandbox Metrics：虚拟机内部envd进程

监控视角：

HostStats：宿主机内核视角

Sandbox Metrics：虚拟机操作系统视角

CPU相关数据：

HostStats：进程CPU时长、cgroup CPU耗时

Sandbox Metrics：虚拟机整体CPU使用率

内存相关数据：

HostStats：进程常驻/虚拟内存、cgroup当前内存/内存峰值

Sandbox Metrics：虚拟机总内存、已用内存

磁盘相关数据：

HostStats：无磁盘监控

Sandbox Metrics：虚拟机根分区总容量、已用容量

时间戳来源：

HostStats：宿主机系统时间

Sandbox Metrics：虚拟机系统时间（用于时间校验）

数据传输方式：

HostStats：本地函数读取文件，无网络请求

Sandbox Metrics：HTTP接口上报数据

数据最终去向：

HostStats：ClickHouse

Sandbox Metrics：OpenTelemetry Collector

数据精度特点：

HostStats：可精准定位到单个进程

Sandbox Metrics：反映虚拟机整体资源状态

## 5. 整体业务流程说明

### 5.1 宿主机层HostStats数据流转

1. 沙箱实例启动，初始化宿主机数据采集器

2. 绑定Firecracker进程ID、cgroup管理句柄，启动后台采集协程

3. 采集器同时读取两类数据：一是Firecracker进程内存、CPU数据；二是cgroup内核CPU、内存数据

4. 整合所有数据，统一推送至ClickHouse数据库存储

### 5.2 虚拟机层数据流转（虚拟机→宿主机→监控平台）

1. 虚拟机内envd守护进程，读取系统CPU、内存、磁盘信息

2. 宿主机Orchestrator通过HTTP接口（超时100毫秒）拉取虚拟机指标

3. 宿主机完成版本校验、时间校验、阈值判断后，将数据转为标准监控指标

4. 指标推送至OpenTelemetry Collector，最终在Prometheus、Grafana等平台展示

### 5.3 双层监控整体流转

1. 宿主机层：采集器读取进程与cgroup数据，推送至ClickHouse

2. 虚拟机层：envd采集系统数据，通过HTTP接口上报给宿主机

3. 宿主机统一处理虚拟机上报数据，转为标准监控指标对外提供查询

4. 两套数据相互补充、对照分析

### 5.4 虚拟机层完整定时采集流程（每5秒执行一轮）

1. 监控框架注册定时回调，每5秒触发一次全量沙箱指标采集

2. 遍历所有正在运行的沙箱，控制HTTP请求并发数量，防止服务过载

3. 逐个校验沙箱内envd版本，版本低于0.1.5直接跳过，不采集数据

4. 版本合规则发起HTTP请求，调用虚拟机/metrics接口获取原始指标

5. 虚拟机内envd读取本地CPU、内存、磁盘数据，组装成数据报文返回宿主机

6. 宿主机接收数据后，第一步做时间校验：虚拟机与宿主机时间差超过2秒则告警

7. 根据envd版本处理内存单位，低版本完成单位换算，高版本直接使用原始数据

8. 将CPU、内存、磁盘数据注册为标准监控指标，并绑定沙箱、租户标识

9. 计算CPU、内存使用率，超过80%阈值则输出资源告警日志

10. 当前沙箱处理完毕，继续处理下一个沙箱，直至全部遍历完成

11. 本轮所有数据汇总后，统一推送至监控采集器，供前端监控页面展示

## 6. 两套体系使用定位总结

1. HostStats（宿主机监控）：统计Firecracker进程真实占用的硬件资源，核心用途是业务计费、宿主机整体资源调度。

2. Sandbox Metrics（虚拟机自监控）：展示虚拟机内部系统感知到的资源压力，核心用途是面向终端用户展示监控、资源异常告警、集群容量规划。