Skip to content

Commit 4437d06

Browse files
ZhiXiao-LinRoy Lin
andauthored
docs: document snapshot prune + auto-prune env and pool --metrics-addr (#137)
Per CLAUDE.md (docs reflect completed features): the operability batch added 'snapshot prune --keep/--max-bytes' + A3S_BOX_MAX_SNAPSHOTS/_BYTES auto-prune (bound snapshot disk) and 'pool start --metrics-addr' (Prometheus /metrics for the warm-pool daemon). README's snapshots + warm-pool sections now show them. Co-authored-by: Roy Lin <roylin@a3s.box>
1 parent 5d23c02 commit 4437d06

1 file changed

Lines changed: 6 additions & 0 deletions

File tree

README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,10 +210,13 @@ a3s-box export app -o rootfs.tar
210210
a3s-box commit app -t app:snapshot
211211
a3s-box snapshot create app checkpoint-1
212212
a3s-box snapshot restore checkpoint-1 --name restored-app
213+
a3s-box snapshot prune --keep 5 # bound disk: keep the 5 newest
213214
```
214215

215216
The `snapshot` command produces configuration/filesystem-oriented Box snapshots, not a live RAM checkpoint. The live RAM Copy-on-Write facility is a separate, lower-level mechanism described in [Warm pool and snapshot-fork](#warm-pool-and-snapshot-fork).
216217

218+
Each snapshot deep-copies the box rootfs, so a scheduled snapshot workflow can fill the disk. `snapshot prune --keep N` / `--max-bytes B` evicts the oldest beyond a cap; set `A3S_BOX_MAX_SNAPSHOTS` / `A3S_BOX_MAX_SNAPSHOT_BYTES` to auto-prune on every `snapshot create` (unset = unbounded).
219+
217220
## Warm pool and snapshot-fork
218221

219222
A **warm pool** keeps a set of sandboxes pre-booted and serves them over a Unix
@@ -225,11 +228,14 @@ json-file console logs).
225228
```bash
226229
a3s-box pool start --image alpine:latest --size 8 # pre-warm 8 sandboxes
227230
a3s-box pool start --image alpine:latest --size 8 --snapshot-fork # CoW fill
231+
a3s-box pool start --image alpine:latest --metrics-addr 127.0.0.1:9101 # + Prometheus /metrics
228232
a3s-box pool run alpine:latest -- echo hi # served from the pool
229233
a3s-box pool status
230234
a3s-box pool stop
231235
```
232236

237+
`pool start --metrics-addr` serves a Prometheus `/metrics` endpoint with warm-pool hit/miss, VM-boot, and cache metrics for the long-running daemon (alongside `monitor --metrics-addr`'s box-state metrics + `/healthz`).
238+
233239
**Snapshot-fork** (`--snapshot-fork`, Linux `/dev/kvm` only) is native
234240
Copy-on-Write microVM cloning. The pool cold-boots one template sandbox,
235241
snapshots its file-backed guest RAM together with KVM vCPU and virtio device

0 commit comments

Comments
 (0)