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