Patchwork [3/3] docs: document virtio-balloon stats

login
register
mail settings
Submitter Luiz Capitulino
Date Jan. 18, 2013, 7:29 p.m.
Message ID <1358537372-27320-4-git-send-email-lcapitulino@redhat.com>
Download mbox | patch
Permalink /patch/213736/
State New
Headers show

Comments

Luiz Capitulino - Jan. 18, 2013, 7:29 p.m.
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
Eric Blake - Jan. 18, 2013, 8 p.m.
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.
Luiz Capitulino - Jan. 21, 2013, 11:56 a.m.
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.

Patch

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": {} }