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
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
20Once polling is enabled, the virtio-balloon device in QEMU will start
21polling the guest's balloon driver for new stats in the specified time
22interval.
23
24To retrieve those stats, clients have to query the guest-stats property,
25which 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
47It'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
66Here are a few examples. QEMU is started with ``-device virtio-balloon``,
67which generates ``/machine/peripheral-anon/device[1]`` as the QOM path for
68the balloon device.
69
70Enable 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
78Change 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
86Get 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
105Disable polling::
106
107  { "execute": "qom-set",
108               "arguments": { "path": "/machine/peripheral-anon/device[1]",
109               "property": "stats-polling-interval", "value": 0 } }
110
111  { "return": {} }
112