14dc58e3e0
The virtio-balloon-stats documentation might be useful for people that are implementing software that talks to QEMU via QMP, so this should reside in the docs/interop/ directory. While we're at it, also convert the file to restructured text and mention it in the MAINTAINERS file. Signed-off-by: Thomas Huth <thuth@redhat.com> Message-Id: <20220105115245.420945-1-thuth@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
112 lines
3.8 KiB
ReStructuredText
112 lines
3.8 KiB
ReStructuredText
Virtio balloon memory statistics
|
|
================================
|
|
|
|
The virtio balloon driver supports guest memory statistics reporting. These
|
|
statistics are available to QEMU users as QOM (QEMU Object Model) device
|
|
properties via a polling mechanism.
|
|
|
|
Before querying the available stats, clients first have to enable polling.
|
|
This is done by writing a time interval value (in seconds) to the
|
|
guest-stats-polling-interval property. This value can be:
|
|
|
|
> 0
|
|
enables polling in the specified interval. If polling is already
|
|
enabled, the polling time interval is changed to the new value
|
|
|
|
0
|
|
disables polling. Previous polled statistics are still valid and
|
|
can be queried.
|
|
|
|
Once polling is enabled, the virtio-balloon device in QEMU will start
|
|
polling the guest's balloon driver for new stats in the specified time
|
|
interval.
|
|
|
|
To retrieve those stats, clients have to query the guest-stats property,
|
|
which will return a dictionary containing:
|
|
|
|
* A key named 'stats', containing all available stats. If the guest
|
|
doesn't support a particular stat, or if it couldn't be retrieved,
|
|
its value will be -1. Currently, the following stats are supported:
|
|
|
|
- stat-swap-in
|
|
- stat-swap-out
|
|
- stat-major-faults
|
|
- stat-minor-faults
|
|
- stat-free-memory
|
|
- stat-total-memory
|
|
- stat-available-memory
|
|
- stat-disk-caches
|
|
- stat-htlb-pgalloc
|
|
- stat-htlb-pgfail
|
|
|
|
* A key named last-update, which contains the last stats update
|
|
timestamp in seconds. Since this timestamp is generated by the host,
|
|
a buggy guest can't influence its value. The value is 0 if the guest
|
|
has not updated the stats (yet).
|
|
|
|
It's also important to note the following:
|
|
|
|
- Previously polled statistics remain available even if the polling is
|
|
later disabled
|
|
|
|
- As noted above, if a guest doesn't support a particular stat its value
|
|
will always be -1. However, it's also possible that a guest temporarily
|
|
couldn't update one or even all stats. If this happens, just wait for
|
|
the next update
|
|
|
|
- Polling can be enabled even if the guest doesn't have stats support
|
|
or the balloon driver wasn't loaded in the guest. If this is the case
|
|
and stats are queried, last-update will be 0.
|
|
|
|
- The polling timer is only re-armed when the guest responds to the
|
|
statistics request. This means that if a (buggy) guest doesn't ever
|
|
respond to the request the timer will never be re-armed, which has
|
|
the same effect as disabling polling
|
|
|
|
Here are a few examples. QEMU is started with ``-device virtio-balloon``,
|
|
which generates ``/machine/peripheral-anon/device[1]`` as the QOM path for
|
|
the balloon device.
|
|
|
|
Enable polling with 2 seconds interval::
|
|
|
|
{ "execute": "qom-set",
|
|
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
|
"property": "guest-stats-polling-interval", "value": 2 } }
|
|
|
|
{ "return": {} }
|
|
|
|
Change polling to 10 seconds::
|
|
|
|
{ "execute": "qom-set",
|
|
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
|
"property": "guest-stats-polling-interval", "value": 10 } }
|
|
|
|
{ "return": {} }
|
|
|
|
Get stats::
|
|
|
|
{ "execute": "qom-get",
|
|
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
|
"property": "guest-stats" } }
|
|
{
|
|
"return": {
|
|
"stats": {
|
|
"stat-swap-out": 0,
|
|
"stat-free-memory": 844943360,
|
|
"stat-minor-faults": 219028,
|
|
"stat-major-faults": 235,
|
|
"stat-total-memory": 1044406272,
|
|
"stat-swap-in": 0
|
|
},
|
|
"last-update": 1358529861
|
|
}
|
|
}
|
|
|
|
Disable polling::
|
|
|
|
{ "execute": "qom-set",
|
|
"arguments": { "path": "/machine/peripheral-anon/device[1]",
|
|
"property": "stats-polling-interval", "value": 0 } }
|
|
|
|
{ "return": {} }
|