blob: 7a66d25da5fd04d4a41a978685e5b87b32c43471 [file] [log] [blame]
Luiz Capitulino045a7082012-12-04 12:04:39 -02001virtio 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 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
18Once polling is enabled, the virtio-balloon device in QEMU will start
19polling the guest's balloon driver for new stats in the specified time
20interval.
21
22To retrieve those stats, clients have to query the guest-stats property,
23which 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
Tomáš Golembiovskýc5e93162018-02-19 13:43:44 +010035 - stat-available-memory
36 - stat-disk-caches
Luiz Capitulino045a7082012-12-04 12:04:39 -020037
38 o A key named last-update, which contains the last stats update
39 timestamp in seconds. Since this timestamp is generated by the host,
Ján Tomko38dbd482014-05-21 11:03:47 +020040 a buggy guest can't influence its value. The value is 0 if the guest
41 has not updated the stats (yet).
Luiz Capitulino045a7082012-12-04 12:04:39 -020042
43It's also important to note the following:
44
45 - Previously polled statistics remain available even if the polling is
46 later disabled
47
48 - As noted above, if a guest doesn't support a particular stat its value
49 will always be -1. However, it's also possible that a guest temporarily
50 couldn't update one or even all stats. If this happens, just wait for
51 the next update
52
53 - Polling can be enabled even if the guest doesn't have stats support
54 or the balloon driver wasn't loaded in the guest. If this is the case
Ján Tomko38dbd482014-05-21 11:03:47 +020055 and stats are queried, last-update will be 0.
Luiz Capitulino045a7082012-12-04 12:04:39 -020056
57 - The polling timer is only re-armed when the guest responds to the
58 statistics request. This means that if a (buggy) guest doesn't ever
59 respond to the request the timer will never be re-armed, which has
60 the same effect as disabling polling
61
62Here are a few examples. QEMU is started with '-balloon virtio', which
63generates '/machine/peripheral-anon/device[1]' as the QOM path for the
64balloon device.
65
66Enable polling with 2 seconds interval:
67
68{ "execute": "qom-set",
69 "arguments": { "path": "/machine/peripheral-anon/device[1]",
70 "property": "guest-stats-polling-interval", "value": 2 } }
71
72{ "return": {} }
73
74Change polling to 10 seconds:
75
76{ "execute": "qom-set",
77 "arguments": { "path": "/machine/peripheral-anon/device[1]",
78 "property": "guest-stats-polling-interval", "value": 10 } }
79
80{ "return": {} }
81
82Get stats:
83
84{ "execute": "qom-get",
85 "arguments": { "path": "/machine/peripheral-anon/device[1]",
86 "property": "guest-stats" } }
87{
88 "return": {
89 "stats": {
90 "stat-swap-out": 0,
91 "stat-free-memory": 844943360,
92 "stat-minor-faults": 219028,
93 "stat-major-faults": 235,
94 "stat-total-memory": 1044406272,
95 "stat-swap-in": 0
96 },
97 "last-update": 1358529861
98 }
99}
100
101Disable polling:
102
103{ "execute": "qom-set",
104 "arguments": { "path": "/machine/peripheral-anon/device[1]",
105 "property": "stats-polling-interval", "value": 0 } }
106
107{ "return": {} }