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