Luiz Capitulino | 045a708 | 2012-12-04 12:04:39 -0200 | [diff] [blame] | 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 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 | |
| 18 | Once polling is enabled, the virtio-balloon device in QEMU will start |
| 19 | polling the guest's balloon driver for new stats in the specified time |
| 20 | interval. |
| 21 | |
| 22 | To retrieve those stats, clients have to query the guest-stats property, |
| 23 | which 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, |
Ján Tomko | 38dbd48 | 2014-05-21 11:03:47 +0200 | [diff] [blame] | 38 | a buggy guest can't influence its value. The value is 0 if the guest |
| 39 | has not updated the stats (yet). |
Luiz Capitulino | 045a708 | 2012-12-04 12:04:39 -0200 | [diff] [blame] | 40 | |
| 41 | It'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 |
Ján Tomko | 38dbd48 | 2014-05-21 11:03:47 +0200 | [diff] [blame] | 53 | and stats are queried, last-update will be 0. |
Luiz Capitulino | 045a708 | 2012-12-04 12:04:39 -0200 | [diff] [blame] | 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 | |
| 60 | Here are a few examples. QEMU is started with '-balloon virtio', which |
| 61 | generates '/machine/peripheral-anon/device[1]' as the QOM path for the |
| 62 | balloon device. |
| 63 | |
| 64 | Enable 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 | |
| 72 | Change 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 | |
| 80 | Get 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 | |
| 99 | Disable polling: |
| 100 | |
| 101 | { "execute": "qom-set", |
| 102 | "arguments": { "path": "/machine/peripheral-anon/device[1]", |
| 103 | "property": "stats-polling-interval", "value": 0 } } |
| 104 | |
| 105 | { "return": {} } |