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