| Message ID | 1358537372-27320-4-git-send-email-lcapitulino@redhat.com |
|---|---|
| State | New |
| Headers | show |
On 01/18/2013 12:29 PM, Luiz Capitulino wrote: > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> > --- > docs/virtio-balloon-stats.txt | 102 ++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 102 insertions(+) > create mode 100644 docs/virtio-balloon-stats.txt > > + > + o A key named 'stats', containing all avaiable stats. If the guest s/avaiable/available/ > + doesn't support a particular stat, 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 > + > + o A key named last-update, which contains the last stats update > + timestamp in seconds Is it worth mentioning that this is a timestamp relative to the Unix epoch? For that matter, does it even matter what the timestamp is relative to, or just that it increases when a new poll completes? Is it worth mentioning that the timestamp is computed by the host (that is, a broken guest can't fake the timestamp, even if it can provide bogus data for all the stats)? > + > + - As noted above, if a guest doesn't support a particular stat it > + will always be -1. However, it's also possible that a guest couldn't > + temporarily update one or even all stats. If this happens, just wait s/couldn't temporarily/temporarily couldn't/ > + > +Here are a few examples. The virtio-balloon device is assumed to be in the > +'/machine/peripheral-anon/device[1]' QOM path. Is this QOM path stable, or can it change depending on target architecture and/or command-line arguments used to install the guest? It might be worth showing which command line arguments set up this particular QOM path.
On Fri, 18 Jan 2013 13:00:28 -0700 Eric Blake <eblake@redhat.com> wrote: > On 01/18/2013 12:29 PM, Luiz Capitulino wrote: > > Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> > > --- > > docs/virtio-balloon-stats.txt | 102 ++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 102 insertions(+) > > create mode 100644 docs/virtio-balloon-stats.txt > > > > > + > > + o A key named 'stats', containing all avaiable stats. If the guest > > s/avaiable/available/ OK. > > + doesn't support a particular stat, 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 > > + > > + o A key named last-update, which contains the last stats update > > + timestamp in seconds > > Is it worth mentioning that this is a timestamp relative to the Unix > epoch? For that matter, does it even matter what the timestamp is > relative to, or just that it increases when a new poll completes? Yes, I think this field is only important to calculate the delta between updates. > Is it > worth mentioning that the timestamp is computed by the host (that is, a > broken guest can't fake the timestamp, even if it can provide bogus data > for all the stats)? I can mention that. > > + > > + - As noted above, if a guest doesn't support a particular stat it > > + will always be -1. However, it's also possible that a guest couldn't > > + temporarily update one or even all stats. If this happens, just wait > > s/couldn't temporarily/temporarily couldn't/ OK. > > + > > +Here are a few examples. The virtio-balloon device is assumed to be in the > > +'/machine/peripheral-anon/device[1]' QOM path. > > Is this QOM path stable, or can it change depending on target > architecture and/or command-line arguments used to install the guest? I think it can change. > It might be worth showing which command line arguments set up this > particular QOM path. Will do.
diff --git a/docs/virtio-balloon-stats.txt b/docs/virtio-balloon-stats.txt new file mode 100644 index 0000000..621145e --- /dev/null +++ b/docs/virtio-balloon-stats.txt @@ -0,0 +1,102 @@ +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: + + o A key named 'stats', containing all avaiable stats. If the guest + doesn't support a particular stat, 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 + + o A key named last-update, which contains the last stats update + timestamp in seconds + +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 it + will always be -1. However, it's also possible that a guest couldn't + temporarily update one or even all stats. If this happens, just wait + for the next update + + - If polling is enabled but the guest doesn't have stats support or + the balloon driver is not loaded, an error will be returned when + querying stats + + - 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. The virtio-balloon device is assumed to be in the +'/machine/peripheral-anon/device[1]' QOM path. + +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": {} }
Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com> --- docs/virtio-balloon-stats.txt | 102 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 docs/virtio-balloon-stats.txt