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