# 监控指标
<subtitle>查看沙箱 CPU、内存和磁盘使用情况，用于排查性能问题和观察资源趋势。</subtitle>

UCloud Sandbox 会采集沙箱的资源使用指标，包括 CPU、内存和磁盘。通过这些指标，您可以观察任务负载、定位性能瓶颈，或判断沙箱资源配置是否合适。

## 指标内容

系统会周期性采集指标数据。获取到的指标通常包含以下维度：

- **CPU**：CPU 核心数量和当前使用率。
- **内存**：总内存和当前已用内存。
- **磁盘**：总磁盘空间和当前已用磁盘空间。
- **时间戳**：每个指标点对应的采集时间。

> 沙箱刚创建后，监控组件可能需要几秒钟才会产生第一批指标。在此之前，SDK 获取结果可能为空。

## 使用 SDK 获取指标

调用 `get_metrics()` 可以获取沙箱的历史指标数据。指标会以带时间戳的数组返回。

```python
from time import sleep
from ucloud_sandbox import Sandbox

sbx = Sandbox.create()
print("沙箱已创建", sbx.sandbox_id)

# 等待一段时间，让系统采集初始指标
sleep(10)

metrics = sbx.get_metrics()

# 也可以通过沙箱 ID 获取：
# metrics = Sandbox.get_metrics(sbx.sandbox_id)

for m in metrics:
    mem_used_mib = m.mem_used / 1024**2
    mem_total_mib = m.mem_total / 1024**2
    disk_used_mib = m.disk_used / 1024**2
    disk_total_mib = m.disk_total / 1024**2

    print(
        f"[{m.timestamp}] "
        f"CPU: {m.cpu_used_pct:.2f}% / {m.cpu_count} Cores | "
        f"Memory: {mem_used_mib:.0f} / {mem_total_mib:.0f} MiB | "
        f"Disk: {disk_used_mib:.0f} / {disk_total_mib:.0f} MiB"
    )
```

## 使用 CLI 查看指标

也可以通过 UCloud Sandbox CLI 查看沙箱指标：

```bash
ucloud-sandbox-cli sandbox metrics <sandbox-id>
```

输出示例：

```text
Sandbox: iaba1wkrrkyjswxoo4q6e  (21 samples)

── CPU Usage (%)
 100.00 ┤
  87.50 ┤
  75.00 ┤
  62.50 ┤
  50.00 ┤
  37.50 ┤
  25.00 ┤
  12.50 ┼╮
   0.00 ┤╰───────────────────
        └┬────┬────┬────┬────┬
     15:00:30  15:01:20  15:02:10

── Memory Usage (%)
 100.00 ┤
  87.50 ┤
  75.00 ┤
  62.50 ┤
  50.00 ┤
  37.50 ┤
  25.00 ┤
  12.50 ┼────────────────────
   0.00 ┤
        └┬────┬────┬────┬────┬
     15:00:30  15:01:20  15:02:10

── Disk Usage (%)
 100.00 ┤
  87.50 ┤
  75.00 ┤
  62.50 ┤
  50.00 ┤
  37.50 ┤
  25.00 ┤
  12.50 ┼────────────────────
   0.00 ┤
        └┬────┬────┬────┬────┬
     15:00:30  15:01:20  15:02:10
```

CLI 输出会将采集到的样本绘制成 CPU、内存和磁盘使用率曲线，方便直接在终端观察资源变化趋势。

## 注意事项

- 指标主要用于观察运行趋势和排查问题，不建议作为精确计费依据。
- 如果沙箱刚创建不久，可能需要等待几秒后再获取指标。
- 如果沙箱已被销毁，则无法继续获取该沙箱的运行指标。