Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging
[qemu.git] / docs / virtio-balloon-stats.txt
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       - stat-available-memory
36       - stat-disk-caches
37       - stat-htlb-pgalloc
38       - stat-htlb-pgfail
39
40   o A key named last-update, which contains the last stats update
41     timestamp in seconds. Since this timestamp is generated by the host,
42     a buggy guest can't influence its value. The value is 0 if the guest
43     has not updated the stats (yet).
44
45 It's also important to note the following:
46
47  - Previously polled statistics remain available even if the polling is
48    later disabled
49
50  - As noted above, if a guest doesn't support a particular stat its value
51    will always be -1. However, it's also possible that a guest temporarily
52    couldn't update one or even all stats. If this happens, just wait for
53    the next update
54
55  - Polling can be enabled even if the guest doesn't have stats support
56    or the balloon driver wasn't loaded in the guest. If this is the case
57    and stats are queried, last-update will be 0.
58
59  - The polling timer is only re-armed when the guest responds to the
60    statistics request. This means that if a (buggy) guest doesn't ever
61    respond to the request the timer will never be re-armed, which has
62    the same effect as disabling polling
63
64 Here are a few examples. QEMU is started with '-device virtio-balloon',
65 which generates '/machine/peripheral-anon/device[1]' as the QOM path for
66 the balloon device.
67
68 Enable polling with 2 seconds interval:
69
70 { "execute": "qom-set",
71              "arguments": { "path": "/machine/peripheral-anon/device[1]",
72                          "property": "guest-stats-polling-interval", "value": 2 } }
73
74 { "return": {} }
75
76 Change polling to 10 seconds:
77
78 { "execute": "qom-set",
79              "arguments": { "path": "/machine/peripheral-anon/device[1]",
80                          "property": "guest-stats-polling-interval", "value": 10 } }
81
82 { "return": {} }
83
84 Get stats:
85
86 { "execute": "qom-get",
87   "arguments": { "path": "/machine/peripheral-anon/device[1]",
88   "property": "guest-stats" } }
89 {
90     "return": {
91         "stats": {
92             "stat-swap-out": 0,
93             "stat-free-memory": 844943360,
94             "stat-minor-faults": 219028,
95             "stat-major-faults": 235,
96             "stat-total-memory": 1044406272,
97             "stat-swap-in": 0
98         },
99         "last-update": 1358529861
100     }
101 }
102
103 Disable polling:
104
105 { "execute": "qom-set",
106              "arguments": { "path": "/machine/peripheral-anon/device[1]",
107                          "property": "stats-polling-interval", "value": 0 } }
108
109 { "return": {} }