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 36 o A key named last-update, which contains the last stats update 37 timestamp in seconds. Since this timestamp is generated by the host, 38 a buggy guest can't influence its value. The value is 0 if the guest 39 has not updated the stats (yet). 40 41It's also important to note the following: 42 43 - Previously polled statistics remain available even if the polling is 44 later disabled 45 46 - As noted above, if a guest doesn't support a particular stat its value 47 will always be -1. However, it's also possible that a guest temporarily 48 couldn't update one or even all stats. If this happens, just wait for 49 the next update 50 51 - Polling can be enabled even if the guest doesn't have stats support 52 or the balloon driver wasn't loaded in the guest. If this is the case 53 and stats are queried, last-update will be 0. 54 55 - The polling timer is only re-armed when the guest responds to the 56 statistics request. This means that if a (buggy) guest doesn't ever 57 respond to the request the timer will never be re-armed, which has 58 the same effect as disabling polling 59 60Here are a few examples. QEMU is started with '-balloon virtio', which 61generates '/machine/peripheral-anon/device[1]' as the QOM path for the 62balloon device. 63 64Enable polling with 2 seconds interval: 65 66{ "execute": "qom-set", 67 "arguments": { "path": "/machine/peripheral-anon/device[1]", 68 "property": "guest-stats-polling-interval", "value": 2 } } 69 70{ "return": {} } 71 72Change polling to 10 seconds: 73 74{ "execute": "qom-set", 75 "arguments": { "path": "/machine/peripheral-anon/device[1]", 76 "property": "guest-stats-polling-interval", "value": 10 } } 77 78{ "return": {} } 79 80Get stats: 81 82{ "execute": "qom-get", 83 "arguments": { "path": "/machine/peripheral-anon/device[1]", 84 "property": "guest-stats" } } 85{ 86 "return": { 87 "stats": { 88 "stat-swap-out": 0, 89 "stat-free-memory": 844943360, 90 "stat-minor-faults": 219028, 91 "stat-major-faults": 235, 92 "stat-total-memory": 1044406272, 93 "stat-swap-in": 0 94 }, 95 "last-update": 1358529861 96 } 97} 98 99Disable polling: 100 101{ "execute": "qom-set", 102 "arguments": { "path": "/machine/peripheral-anon/device[1]", 103 "property": "stats-polling-interval", "value": 0 } } 104 105{ "return": {} } 106