Health and compact
Operator-facing trust signals and the v1 compact rewrite. Auth is required on all /api/* routes. See HTTP API.
Health endpoints
GET /api/v1/health
Liveness probe. Success body is roughly {"ok":true,"tenant":"default"}. Useful to check whether serve is up. It does not report corruption or WAL lag.
GET /api/v1/health/detail
The trust surface. JSON includes:
| Field | Meaning for operators |
|---|---|
corruption.total / corruption.reports | Checksum failures with identity and counts. Failures are recorded and exposed here. |
wal.current_lsn / checkpoint_lsn / lag_bytes / bytes | Tip vs last checkpoint; how much WAL is still outstanding |
recovery.replayed_frames / open_micros | What the last open had to replay, and how long recovery took |
fsync histogram | Count / max / bucketed latencies of durable WAL syncs this session |
page_count / db_dir | Allocator tip and path of the open database |
Studio's Health panel is built entirely on this endpoint: healthy vs corrupt badge, WAL lag, last-open recovery line, fsync histogram.
GET /api/v1/stats
Lighter engine stats for the Studio footer: page_count, wal_bytes, checkpoint_lsn, corruption_count, db_dir. Same corruption total as detail (sum of report counts), without the full report list or fsync histogram.
Corruption reporting
Page slots carry checksums. A durable slot that fails verification is recorded and surfaced on /health/detail and /stats. The engine does not treat a bad checksum as good data. Treat a non-zero corruption count as data loss detected. Reseed or restore from a known-good db_dir copy when you have one.
Compact (v1)
Rewrites live rows for one tenant into fresh pages. Fork and snapshot pins stay readable. Compact does not rewrite away history those pins need.
CLI
cargo run -p eelgrass-cli -- compact ./mydb
cargo run -p eelgrass-cli -- compact ./mydb acmeDefault tenant is default. Success prints collection/row counts and elapsed ms. Full argv table: CLI: compact.
HTTP / Studio
POST /api/v1/t/:tenant/ops with {"op":"compact"} (uses the path tenant). Response: {"ok":true,"message":"compacted: …"}. Same op is available from Studio tenant ops when write mode is on.
v1 limits
- Rewrites live data for the bound tenant. It is not the full page-history /
@breakinghistory-compacting rewrite listed under Status “what's next”. - Physical reclaim of orphaned page slots remains deferred. Compact swings collection roots to new trees; disk may not shrink the way a filesystem “vacuum” would.
- Run when live trees are bloated with tombstones or you want fresh pages. Recreate a corrupt directory instead of relying on compact alone.