qemu/docs/virtio-balloon-stats.txt
<<
>>
Prefs
   1virtio balloon memory statistics
   2================================
   3
   4The virtio balloon driver supports guest memory statistics reporting. These
   5statistics are available to QEMU users as QOM (QEMU Object Model) device
   6properties via a polling mechanism.
   7
   8Before querying the available stats, clients first have to enable polling.
   9This is done by writing a time interval value (in seconds) to the
  10guest-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
  18Once polling is enabled, the virtio-balloon device in QEMU will start
  19polling the guest's balloon driver for new stats in the specified time
  20interval.
  21
  22To retrieve those stats, clients have to query the guest-stats property,
  23which 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      - stat-available-memory
  36      - stat-disk-caches
  37      - stat-htlb-pgalloc
  38      - stat-htlb-pgfail
  39
  40  o A key named last-update, which contains the last stats update
  41    timestamp in seconds. Since this timestamp is generated by the host,
  42    a buggy guest can't influence its value. The value is 0 if the guest
  43    has not updated the stats (yet).
  44
  45It's also important to note the following:
  46
  47 - Previously polled statistics remain available even if the polling is
  48   later disabled
  49
  50 - As noted above, if a guest doesn't support a particular stat its value
  51   will always be -1. However, it's also possible that a guest temporarily
  52   couldn't update one or even all stats. If this happens, just wait for
  53   the next update
  54
  55 - Polling can be enabled even if the guest doesn't have stats support
  56   or the balloon driver wasn't loaded in the guest. If this is the case
  57   and stats are queried, last-update will be 0.
  58
  59 - The polling timer is only re-armed when the guest responds to the
  60   statistics request. This means that if a (buggy) guest doesn't ever
  61   respond to the request the timer will never be re-armed, which has
  62   the same effect as disabling polling
  63
  64Here are a few examples. QEMU is started with '-device virtio-balloon',
  65which generates '/machine/peripheral-anon/device[1]' as the QOM path for
  66the balloon device.
  67
  68Enable polling with 2 seconds interval:
  69
  70{ "execute": "qom-set",
  71             "arguments": { "path": "/machine/peripheral-anon/device[1]",
  72                         "property": "guest-stats-polling-interval", "value": 2 } }
  73
  74{ "return": {} }
  75
  76Change polling to 10 seconds:
  77
  78{ "execute": "qom-set",
  79             "arguments": { "path": "/machine/peripheral-anon/device[1]",
  80                         "property": "guest-stats-polling-interval", "value": 10 } }
  81
  82{ "return": {} }
  83
  84Get stats:
  85
  86{ "execute": "qom-get",
  87  "arguments": { "path": "/machine/peripheral-anon/device[1]",
  88  "property": "guest-stats" } }
  89{
  90    "return": {
  91        "stats": {
  92            "stat-swap-out": 0,
  93            "stat-free-memory": 844943360,
  94            "stat-minor-faults": 219028,
  95            "stat-major-faults": 235,
  96            "stat-total-memory": 1044406272,
  97            "stat-swap-in": 0
  98        },
  99        "last-update": 1358529861
 100    }
 101}
 102
 103Disable polling:
 104
 105{ "execute": "qom-set",
 106             "arguments": { "path": "/machine/peripheral-anon/device[1]",
 107                         "property": "stats-polling-interval", "value": 0 } }
 108
 109{ "return": {} }
 110