| 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": {} } |