docs/interop/virtio-balloon-stats.rst

1 Virtio balloon memory statistics
4 The virtio balloon driver supports guest memory statistics reporting. These
5 statistics are available to QEMU users as QOM (QEMU Object Model) device
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:
14        enabled, the polling time interval is changed to the new value
20 Once polling is enabled, the virtio-balloon device in QEMU will start
24 To retrieve those stats, clients have to query the guest-stats property,
29     its value will be -1. Currently, the following stats are supported:
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
42   * A key named last-update, which contains the last stats update
47 It's also important to note the following:
49  - Previously polled statistics remain available even if the polling is
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
57  - Polling can be enabled even if the guest doesn't have stats support
59    and stats are queried, last-update will be 0.
61  - The polling timer is only re-armed when the guest responds to the
63    respond to the request the timer will never be re-armed, which has
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
72   { "execute": "qom-set",
73                "arguments": { "path": "/machine/peripheral-anon/device[1]",
74                "property": "guest-stats-polling-interval", "value": 2 } }
78 Change polling to 10 seconds::
80   { "execute": "qom-set",
81                "arguments": { "path": "/machine/peripheral-anon/device[1]",
82                "property": "guest-stats-polling-interval", "value": 10 } }
88   { "execute": "qom-get",
89                "arguments": { "path": "/machine/peripheral-anon/device[1]",
90                "property": "guest-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
101         "last-update": 1358529861
107   { "execute": "qom-set",
108                "arguments": { "path": "/machine/peripheral-anon/device[1]",
109                "property": "stats-polling-interval", "value": 0 } }