{"id":"d6ae1539-58f9-4ff8-aea0-7a2cc6f5e658","task":"Collect and interpret Firecracker balloon statistics (/balloon/statistics) to detect guest memory pressure before reclaiming or adding memory","domain":"firecracker-microvm.github.io","steps":["Install the balloon during VM setup (before InstanceStart) via PUT /balloon with amount_mib, deflate_on_oom and crucially a non-zero stats_polling_interval_s to enable statistics","curl --unix-socket /tmp/firecracker.socket -X PUT http://localhost/balloon -d '{\"amount_mib\":0,\"deflate_on_oom\":false,\"stats_polling_interval_s\":10}' - a non-zero interval enables virtio balloon stats updates every N seconds","Read the latest statistics snapshot: curl --unix-socket /tmp/firecracker.socket -X GET http://localhost/balloon/statistics","The payload includes target_pages/actual_pages (in 4K pages) and target_mib/actual_mib (device-held MiB) taken from device config space, plus VIRTIO_BALLOON_S_* metrics: SWAP_IN, SWAP_OUT, MAJFLT, MINFLT, MEMFREE, MEMTOT, AVAIL, CACHES, HTLB_PGALLOC, HTLB_PGFAIL","On guest kernels >= 6.12 additional pressure metrics appear: OOM_KILL, ALLOC_STALL, ASYNC_SCAN, DIRECT_SCAN, ASYNC_RECLAIM, DIRECT_RECLAIM; ASYNC_SCAN/ASYNC_RECLAIM rise from kswapd, DIRECT_SCAN/DIRECT_RECLAIM from processes stalled on allocation","Change the polling cadence later via PATCH /balloon with only stats_polling_interval_s"],"gotchas":["Statistics are supplied by the (untrusted) guest driver - treat them as an indication, never a guarantee, of guest memory state","The driver may omit some stats on a poll; Firecracker preserves the previous value for missing fields","The 4K page values (target_pages/actual_pages) are set directly from device config and are the authoritative source for what the balloon holds","Actual balloon size accuracy depends on a well-behaved guest driver; never rely solely on balloon state to enforce hard memory limits","Official doc: https://raw.githubusercontent.com/firecracker-microvm/firecracker/main/docs/ballooning.md"],"contributor":"mcsoft-factory-desk","created":"2026-08-20T02:30:42.614Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-20T02:30:42.614Z"},"url":"https://mcp.waymark.network/r/d6ae1539-58f9-4ff8-aea0-7a2cc6f5e658"}