feat(metrics): add real-time metrics for a single sandbox

## Background

Add an E2B-compatible sandbox metrics endpoint as the first step toward
historical metrics support. This PR intentionally implements a real-time
single-sandbox snapshot only: start/end are accepted for API
compatibility and filter the current point, but no metrics persistence or
historical range query is introduced yet.

## Summary

Expose GET /sandboxes/:sandboxID/metrics in CubeAPI and proxy the request
to CubeMaster's /cube/sandbox/metrics endpoint. CubeAPI validates the
optional start/end range, maps CubeMaster errors into public API errors,
and converts CubeMaster's snake_case metric payload into the
E2B-compatible camelCase response shape.

Add CubeMaster HTTP routing and service logic for sandbox metrics.
CubeMaster resolves the sandbox's owning Cubelet from local cache, calls
Cubelet over gRPC using the inherited request context, filters the
returned current point by start/end, and guarantees empty results
serialize as data: [] instead of null.

Add Cubelet GetSandboxMetrics support. Cubelet builds a fallback snapshot
from local CubeBox resource metadata, requests envd's /metrics endpoint
for live CPU, memory, cache, and disk usage, and overlays live envd
values when available while preserving fallback behavior for old
templates or transient envd failures.

## Compatibility

The new protobuf messages use stable field numbers for the metrics
request, response, and SandboxMetric fields. Generated pb.go/grpc.pb.go
files are updated from the proto definitions; business logic lives
separately in CubeAPI, CubeMaster, and Cubelet service files.

## Tests

- cargo test metrics
- go test ./pkg/service/httpservice/cube -run 'TestHandleSandboxMetrics|Metrics|RegisterCubeRoutes|InternalHttp' -count=1
- go test ./pkg/service/sandbox -run 'TestMetric|TestSandboxMetrics|Test.*Metrics.*Data|TestSandboxMetricsResponse' -count=1
- go test ./services/cubebox -run 'Test.*SandboxMetric|TestGetSandboxMetrics|TestFirstContainerResources' -count=1

Signed-off-by: zry <1292625211@qq.com>

Author: emailcannotbeblank

CubeAPI/src/cubemaster/mod.rs

@@ -11,6 +11,7 @@
 ///
 /// Implemented on CubeMaster (see pkg/service/sandbox/types):
 ///   - GET    /cube/sandbox/info       get single sandbox detail (query: sandbox_id, instance_type)
+///   - GET    /cube/sandbox/metrics    get single sandbox metrics snapshot
 ///   - POST   /cube/sandbox/update     update sandbox (action: "pause" | "resume")
 /// Implemented on CubeMaster (snapshot APIs):
 ///   - POST   /cube/snapshot                          create runtime snapshot (synchronous terminal result)
@@ -125,6 +126,36 @@ impl CubeMasterClient {
         parse_response(resp).await
     }
 
+    /// GET /cube/sandbox/metrics — fetch one sandbox's current metrics snapshot.
+    /// Query: sandbox_id, instance_type, optional start/end Unix seconds.
+    pub async fn get_sandbox_metrics(
+        &self,
+        sandbox_id: &str,
+        instance_type: &str,
+        start: Option<i64>,
+        end: Option<i64>,
+    ) -> Result<GetSandboxMetricsResponse, CubeMasterError> {
+        let url = format!("{}/cube/sandbox/metrics", self.base_url);
+        let mut query = vec![
+            ("sandbox_id", sandbox_id.to_string()),
+            ("instance_type", instance_type.to_string()),
+        ];
+        if let Some(start) = start {
+            query.push(("start", start.to_string()));
+        }
+        if let Some(end) = end {
+            query.push(("end", end.to_string()));
+        }
+        let resp = self
+            .inner
+            .get(&url)
+            .query(&query)
+            .send()
+            .await
+            .map_err(CubeMasterError::Http)?;
+        parse_response(resp).await
+    }
+
     /// POST /cube/sandbox/update — pause or resume a sandbox (action: "pause" | "resume").
     pub async fn update_sandbox(
         &self,
@@ -1060,6 +1091,37 @@ pub struct GetSandboxContainerItem {
     pub pause_at: i64,
 }
 
+#[derive(Debug, Deserialize)]
+#[allow(dead_code)]
+pub struct GetSandboxMetricsResponse {
+    #[serde(rename = "RequestID", alias = "requestID", default)]
+    pub request_id: String,
+    #[serde(default)]
+    pub data: Vec<SandboxMetricItem>,
+    pub ret: RetCode,
+}
+
+#[derive(Debug, Deserialize, Clone)]
+#[allow(dead_code)]
+pub struct SandboxMetricItem {
+    #[serde(default)]
+    pub timestamp_unix_nano: i64,
+    #[serde(default)]
+    pub cpu_count: i32,
+    #[serde(default)]
+    pub cpu_used_pct: f64,
+    #[serde(default)]
+    pub mem_used: i64,
+    #[serde(default)]
+    pub mem_total: i64,
+    #[serde(default)]
+    pub mem_cache: i64,
+    #[serde(default)]
+    pub disk_used: i64,
+    #[serde(default)]
+    pub disk_total: i64,
+}
+
 /// Normalized sandbox detail used by handlers (built from GetSandboxDataItem).
 #[derive(Debug, Clone)]
 #[allow(dead_code)]

CubeAPI/src/handlers/sandboxes.rs

@@ -16,7 +16,7 @@ use crate::{
     models::{
         ApiError, ConnectSandbox, ListSandboxesQuery, ListSandboxesV2Query, NewSandbox,
         RefreshRequest, ResumedSandbox, Sandbox, SandboxDetail, SandboxLogsQuery,
-        SandboxLogsV2Query, SandboxLogsV2Response, SetTimeoutRequest,
+        SandboxLogsV2Query, SandboxLogsV2Response, SandboxMetricsQuery, SetTimeoutRequest,
     },
     state::AppState,
 };
@@ -154,6 +154,55 @@ pub async fn get_sandbox(
     Ok(Json(detail))
 }
 
+// ─── GET /sandboxes/:sandboxID/metrics ─────────────────────────────────────
+
+/// Handles the public E2B-compatible metrics route and delegates range
+/// validation plus CubeMaster error translation to SandboxService.
+#[utoipa::path(
+    get,
+    path = "/sandboxes/{sandboxID}/metrics",
+    params(
+        ("sandboxID" = String, Path, description = "Sandbox identifier"),
+        SandboxMetricsQuery
+    ),
+    responses(
+        (status = 200, description = "Sandbox metrics", body = [crate::models::SandboxMetric]),
+        (status = 400, description = "Invalid time range", body = ApiError),
+        (status = 404, description = "Sandbox not found", body = ApiError),
+        (status = 500, description = "Unexpected backend error", body = ApiError)
+    )
+)]
+pub async fn get_sandbox_metrics(
+    State(state): State<AppState>,
+    Path(sandbox_id): Path<String>,
+    Query(params): Query<SandboxMetricsQuery>,
+) -> AppResult<impl IntoResponse> {
+    state
+        .logger
+        .log(
+            LogEvent::new(LogLevel::Debug, "api.request")
+                .field("handler", "get_sandbox_metrics")
+                .field("sandbox_id", &sandbox_id),
+        )
+        .await;
+
+    let metrics = state
+        .services
+        .sandboxes
+        .get_metrics(&sandbox_id, params.start, params.end)
+        .await?;
+    state
+        .logger
+        .log(
+            LogEvent::new(LogLevel::Info, "api.response")
+                .field("handler", "get_sandbox_metrics")
+                .field("sandbox_id", &sandbox_id)
+                .field_value("count", metrics.len()),
+        )
+        .await;
+    Ok(Json(metrics))
+}
+
 // ─── POST /sandboxes ──────────────────────────────────────────────────────────
 
 pub async fn create_sandbox(

CubeAPI/src/models/mod.rs

@@ -316,6 +316,39 @@ pub struct SandboxDetail {
     pub volume_mounts: Option<Vec<SandboxVolumeMount>>,
 }
 
+/// Query parameters for GET /sandboxes/{sandboxID}/metrics.
+#[derive(Debug, Deserialize, IntoParams)]
+#[into_params(parameter_in = Query)]
+pub struct SandboxMetricsQuery {
+    /// Unix timestamp for the start of the interval, in seconds.
+    pub start: Option<i64>,
+    /// Unix timestamp for the end of the interval, in seconds.
+    pub end: Option<i64>,
+}
+
+/// One E2B-compatible sandbox metric entry.
+#[derive(Debug, Serialize, Deserialize, ToSchema)]
+pub struct SandboxMetric {
+    /// Deprecated by E2B but still returned for compatibility.
+    pub timestamp: DateTime<Utc>,
+    #[serde(rename = "timestampUnix")]
+    pub timestamp_unix: i64,
+    #[serde(rename = "cpuCount")]
+    pub cpu_count: i32,
+    #[serde(rename = "cpuUsedPct")]
+    pub cpu_used_pct: f64,
+    #[serde(rename = "memUsed")]
+    pub mem_used: i64,
+    #[serde(rename = "memTotal")]
+    pub mem_total: i64,
+    #[serde(rename = "memCache")]
+    pub mem_cache: i64,
+    #[serde(rename = "diskUsed")]
+    pub disk_used: i64,
+    #[serde(rename = "diskTotal")]
+    pub disk_total: i64,
+}
+
 // ─── Sandbox — pause/resume/connect/snapshot ──────────────────────────────
 
 /// Request body for POST /sandboxes/{id}/resume (deprecated).

CubeAPI/src/routes.rs

@@ -120,6 +120,10 @@ fn build_sandbox_routes(state: &AppState, auth_configured: bool) -> Router<AppSt
         .route("/v2/sandboxes", get(sandboxes::list_sandboxes_v2))
         .route("/sandboxes/:sandboxID", get(sandboxes::get_sandbox))
         .route("/sandboxes/:sandboxID", delete(sandboxes::kill_sandbox))
+        .route(
+            "/sandboxes/:sandboxID/metrics",
+            get(sandboxes::get_sandbox_metrics),
+        )
         .route(
             "/sandboxes/:sandboxID/logs",
             get(sandboxes::get_sandbox_logs),
@@ -364,7 +368,7 @@ fn apply_http_layers(router: Router<AppState>, timeout: Duration) -> Router<AppS
 
 #[cfg(test)]
 mod tests {
-    use super::build_router;
+    use super::{build_router, build_sandbox_routes};
     use crate::{
         config::ServerConfig,
         logging::{arc, noop::NoopLogger},
@@ -498,6 +502,40 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn exposes_sandbox_metrics_routes_on_root_and_cubeapi_prefix() {
+        let server = test_server().await;
+
+        server
+            .get("/sandboxes/sb-1/metrics")
+            .add_query_param("start", "2")
+            .add_query_param("end", "1")
+            .await
+            .assert_status(StatusCode::BAD_REQUEST);
+        server
+            .get("/cubeapi/v1/sandboxes/sb-1/metrics")
+            .add_query_param("start", "2")
+            .add_query_param("end", "1")
+            .await
+            .assert_status(StatusCode::BAD_REQUEST);
+    }
+
+    #[tokio::test]
+    async fn sandbox_metrics_route_matches_inside_sandbox_router() {
+        let mut config = ServerConfig::default();
+        config.cubemaster_url = "http://127.0.0.1:9".to_string();
+        let state = AppState::new(config, arc(NoopLogger)).await;
+        let app = build_sandbox_routes(&state, false).with_state(state);
+        let server = TestServer::new(app).expect("sandbox router should build");
+
+        server
+            .get("/sandboxes/sb-1/metrics")
+            .add_query_param("start", "2")
+            .add_query_param("end", "1")
+            .await
+            .assert_status(StatusCode::BAD_REQUEST);
+    }
+
     #[tokio::test]
     async fn auth_login_route_is_rate_limited_without_auth_middleware() {
         let mut config = ServerConfig::default();