virtio-balloon-stats.txt (3741B)
1virtio balloon memory statistics 2================================ 3 4The virtio balloon driver supports guest memory statistics reporting. These 5statistics are available to QEMU users as QOM (QEMU Object Model) device 6properties via a polling mechanism. 7 8Before querying the available stats, clients first have to enable polling. 9This is done by writing a time interval value (in seconds) to the 10guest-stats-polling-interval property. This value can be: 11 12 > 0 enables polling in the specified interval. If polling is already 13 enabled, the polling time interval is changed to the new value 14 15 0 disables polling. Previous polled statistics are still valid and 16 can be queried. 17 18Once polling is enabled, the virtio-balloon device in QEMU will start 19polling the guest's balloon driver for new stats in the specified time 20interval. 21 22To retrieve those stats, clients have to query the guest-stats property, 23which will return a dictionary containing: 24 25 o A key named 'stats', containing all available stats. If the guest 26 doesn't support a particular stat, or if it couldn't be retrieved, 27 its value will be -1. Currently, the following stats are supported: 28 29 - stat-swap-in 30 - stat-swap-out 31 - stat-major-faults 32 - stat-minor-faults 33 - stat-free-memory 34 - stat-total-memory 35 - stat-available-memory 36 - stat-disk-caches 37 - stat-htlb-pgalloc 38 - stat-htlb-pgfail 39 40 o A key named last-update, which contains the last stats update 41 timestamp in seconds. Since this timestamp is generated by the host, 42 a buggy guest can't influence its value. The value is 0 if the guest 43 has not updated the stats (yet). 44 45It's also important to note the following: 46 47 - Previously polled statistics remain available even if the polling is 48 later disabled 49 50 - As noted above, if a guest doesn't support a particular stat its value 51 will always be -1. However, it's also possible that a guest temporarily 52 couldn't update one or even all stats. If this happens, just wait for 53 the next update 54 55 - Polling can be enabled even if the guest doesn't have stats support 56 or the balloon driver wasn't loaded in the guest. If this is the case 57 and stats are queried, last-update will be 0. 58 59 - The polling timer is only re-armed when the guest responds to the 60 statistics request. This means that if a (buggy) guest doesn't ever 61 respond to the request the timer will never be re-armed, which has 62 the same effect as disabling polling 63 64Here are a few examples. QEMU is started with '-device virtio-balloon', 65which generates '/machine/peripheral-anon/device[1]' as the QOM path for 66the balloon device. 67 68Enable polling with 2 seconds interval: 69 70{ "execute": "qom-set", 71 "arguments": { "path": "/machine/peripheral-anon/device[1]", 72 "property": "guest-stats-polling-interval", "value": 2 } } 73 74{ "return": {} } 75 76Change polling to 10 seconds: 77 78{ "execute": "qom-set", 79 "arguments": { "path": "/machine/peripheral-anon/device[1]", 80 "property": "guest-stats-polling-interval", "value": 10 } } 81 82{ "return": {} } 83 84Get stats: 85 86{ "execute": "qom-get", 87 "arguments": { "path": "/machine/peripheral-anon/device[1]", 88 "property": "guest-stats" } } 89{ 90 "return": { 91 "stats": { 92 "stat-swap-out": 0, 93 "stat-free-memory": 844943360, 94 "stat-minor-faults": 219028, 95 "stat-major-faults": 235, 96 "stat-total-memory": 1044406272, 97 "stat-swap-in": 0 98 }, 99 "last-update": 1358529861 100 } 101} 102 103Disable polling: 104 105{ "execute": "qom-set", 106 "arguments": { "path": "/machine/peripheral-anon/device[1]", 107 "property": "stats-polling-interval", "value": 0 } } 108 109{ "return": {} }