qapi/stats.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4 # Copyright (c) 2022 Oracle and/or its affiliates.
   5 #
   6 # This work is licensed under the terms of the GNU GPL, version 2 or later.
   7 # See the COPYING file in the top-level directory.
   8 #
   9 # SPDX-License-Identifier: GPL-2.0-or-later
  10
  11 ##
  12 # = Statistics
  13 ##
  14
  15 ##
  16 # @StatsType:
  17 #
  18 # Enumeration of statistics types
  19 #
  20 # @cumulative: stat is cumulative; value can only increase.
  21 #
  22 # @instant: stat is instantaneous; value can increase or decrease.
  23 #
  24 # @peak: stat is the peak value; value can only increase.
  25 #
  26 # @linear-histogram: stat is a linear histogram.
  27 #
  28 # @log2-histogram: stat is a logarithmic histogram, with one bucket
  29 #     for each power of two.
  30 #
  31 # Since: 7.1
  32 ##
  33 { 'enum' : 'StatsType',
  34   'data' : [ 'cumulative', 'instant', 'peak', 'linear-histogram',
  35              'log2-histogram' ] }
  36
  37 ##
  38 # @StatsUnit:
  39 #
  40 # Enumeration of unit of measurement for statistics
  41 #
  42 # @bytes: stat reported in bytes.
  43 #
  44 # @seconds: stat reported in seconds.
  45 #
  46 # @cycles: stat reported in clock cycles.
  47 #
  48 # @boolean: stat is a boolean value.
  49 #
  50 # Since: 7.1
  51 ##
  52 { 'enum' : 'StatsUnit',
  53   'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] }
  54
  55 ##
  56 # @StatsProvider:
  57 #
  58 # Enumeration of statistics providers.
  59 #
  60 # @kvm: since 7.1
  61 #
  62 # @cryptodev: since 8.0
  63 #
  64 # Since: 7.1
  65 ##
  66 { 'enum': 'StatsProvider',
  67   'data': [ 'kvm', 'cryptodev' ] }
  68
  69 ##
  70 # @StatsTarget:
  71 #
  72 # The kinds of objects on which one can request statistics.
  73 #
  74 # @vm: statistics that apply to the entire virtual machine or the
  75 #     entire QEMU process.
  76 #
  77 # @vcpu: statistics that apply to a single virtual CPU.
  78 #
  79 # @cryptodev: statistics that apply to a crypto device (since 8.0)
  80 #
  81 # Since: 7.1
  82 ##
  83 { 'enum': 'StatsTarget',
  84   'data': [ 'vm', 'vcpu', 'cryptodev' ] }
  85
  86 ##
  87 # @StatsRequest:
  88 #
  89 # Indicates a set of statistics that should be returned by
  90 # query-stats.
  91 #
  92 # @provider: provider for which to return statistics.
  93 #
  94 # @names: statistics to be returned (all if omitted).
  95 #
  96 # Since: 7.1
  97 ##
  98 { 'struct': 'StatsRequest',
  99   'data': { 'provider': 'StatsProvider',
 100             '*names': [ 'str' ] } }
 101
 102 ##
 103 # @StatsVCPUFilter:
 104 #
 105 # @vcpus: list of QOM paths for the desired vCPU objects.
 106 #
 107 # Since: 7.1
 108 ##
 109 { 'struct': 'StatsVCPUFilter',
 110   'data': { '*vcpus': [ 'str' ] } }
 111
 112 ##
 113 # @StatsFilter:
 114 #
 115 # The arguments to the query-stats command; specifies a target for
 116 # which to request statistics and optionally the required subset of
 117 # information for that target.
 118 #
 119 # @target: the kind of objects to query.  Note that each possible
 120 #          target may enable additional filtering options
 121 #
 122 # @providers: which providers to request statistics from, and optionally
 123 #             which named values to return within each provider
 124 #
 125 # Since: 7.1
 126 ##
 127 { 'union': 'StatsFilter',
 128   'base': {
 129       'target': 'StatsTarget',
 130       '*providers': [ 'StatsRequest' ] },
 131   'discriminator': 'target',
 132   'data': { 'vcpu': 'StatsVCPUFilter' } }
 133
 134 ##
 135 # @StatsValue:
 136 #
 137 # @scalar: single unsigned 64-bit integers.
 138 #
 139 # @boolean: single boolean value.
 140 #
 141 # @list: list of unsigned 64-bit integers (used for histograms).
 142 #
 143 # Since: 7.1
 144 ##
 145 { 'alternate': 'StatsValue',
 146   'data': { 'scalar': 'uint64',
 147             'boolean': 'bool',
 148             'list': [ 'uint64' ] } }
 149
 150 ##
 151 # @Stats:
 152 #
 153 # @name: name of stat.
 154 #
 155 # @value: stat value.
 156 #
 157 # Since: 7.1
 158 ##
 159 { 'struct': 'Stats',
 160   'data': { 'name': 'str',
 161             'value' : 'StatsValue' } }
 162
 163 ##
 164 # @StatsResult:
 165 #
 166 # @provider: provider for this set of statistics.
 167 #
 168 # @qom-path: Path to the object for which the statistics are returned,
 169 #     if the object is exposed in the QOM tree
 170 #
 171 # @stats: list of statistics.
 172 #
 173 # Since: 7.1
 174 ##
 175 { 'struct': 'StatsResult',
 176   'data': { 'provider': 'StatsProvider',
 177             '*qom-path': 'str',
 178             'stats': [ 'Stats' ] } }
 179
 180 ##
 181 # @query-stats:
 182 #
 183 # Return runtime-collected statistics for objects such as the VM or
 184 # its vCPUs.
 185 #
 186 # The arguments are a StatsFilter and specify the provider and objects
 187 # to return statistics about.
 188 #
 189 # Returns: a list of StatsResult, one for each provider and object
 190 #     (e.g., for each vCPU).
 191 #
 192 # Since: 7.1
 193 ##
 194 { 'command': 'query-stats',
 195   'data': 'StatsFilter',
 196   'boxed': true,
 197   'returns': [ 'StatsResult' ] }
 198
 199 ##
 200 # @StatsSchemaValue:
 201 #
 202 # Schema for a single statistic.
 203 #
 204 # @name: name of the statistic; each element of the schema is uniquely
 205 #     identified by a target, a provider (both available in
 206 #     @StatsSchema) and the name.
 207 #
 208 # @type: kind of statistic.
 209 #
 210 # @unit: basic unit of measure for the statistic; if missing, the
 211 #     statistic is a simple number or counter.
 212 #
 213 # @base: base for the multiple of @unit in which the statistic is
 214 #     measured.  Only present if @exponent is non-zero; @base and
 215 #     @exponent together form a SI prefix (e.g., _nano-_ for
 216 #     ``base=10`` and ``exponent=-9``) or IEC binary prefix (e.g.
 217 #     _kibi-_ for ``base=2`` and ``exponent=10``)
 218 #
 219 # @exponent: exponent for the multiple of @unit in which the statistic
 220 #     is expressed, or 0 for the basic unit
 221 #
 222 # @bucket-size: Present when @type is "linear-histogram", contains the
 223 #     width of each bucket of the histogram.
 224 #
 225 # Since: 7.1
 226 ##
 227 { 'struct': 'StatsSchemaValue',
 228   'data': { 'name': 'str',
 229             'type': 'StatsType',
 230             '*unit': 'StatsUnit',
 231             '*base': 'int8',
 232             'exponent': 'int16',
 233             '*bucket-size': 'uint32' } }
 234
 235 ##
 236 # @StatsSchema:
 237 #
 238 # Schema for all available statistics for a provider and target.
 239 #
 240 # @provider: provider for this set of statistics.
 241 #
 242 # @target: the kind of object that can be queried through the
 243 #     provider.
 244 #
 245 # @stats: list of statistics.
 246 #
 247 # Since: 7.1
 248 ##
 249 { 'struct': 'StatsSchema',
 250   'data': { 'provider': 'StatsProvider',
 251             'target': 'StatsTarget',
 252             'stats': [ 'StatsSchemaValue' ] } }
 253
 254 ##
 255 # @query-stats-schemas:
 256 #
 257 # Return the schema for all available runtime-collected statistics.
 258 #
 259 # @provider: a provider to restrict the query to.
 260 #
 261 # Note: runtime-collected statistics and their names fall outside
 262 #     QEMU's usual deprecation policies.  QEMU will try to keep the
 263 #     set of available data stable, together with their names, but
 264 #     will not guarantee stability at all costs; the same is true of
 265 #     providers that source statistics externally, e.g. from Linux.
 266 #     For example, if the same value is being tracked with different
 267 #     names on different architectures or by different providers, one
 268 #     of them might be renamed.  A statistic might go away if an
 269 #     algorithm is changed or some code is removed; changing a default
 270 #     might cause previously useful statistics to always report 0.
 271 #     Such changes, however, are expected to be rare.
 272 #
 273 # Since: 7.1
 274 ##
 275 { 'command': 'query-stats-schemas',
 276   'data': { '*provider': 'StatsProvider' },
 277   'returns': [ 'StatsSchema' ] }