qemu

stats.json (6476B)

---

 # -*- Mode: Python -*-
 # vim: filetype=python
 #
 # Copyright (c) 2022 Oracle and/or its affiliates.
 #
 # This work is licensed under the terms of the GNU GPL, version 2 or later.
 # See the COPYING file in the top-level directory.
 #
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 ##
 # = Statistics
 ##
 
 ##
 # @StatsType:
 #
 # Enumeration of statistics types
 #
 # @cumulative: stat is cumulative; value can only increase.
 # @instant: stat is instantaneous; value can increase or decrease.
 # @peak: stat is the peak value; value can only increase.
 # @linear-histogram: stat is a linear histogram.
 # @log2-histogram: stat is a logarithmic histogram, with one bucket
 #                  for each power of two.
 #
 # Since: 7.1
 ##
 { 'enum' : 'StatsType',
   'data' : [ 'cumulative', 'instant', 'peak', 'linear-histogram',
              'log2-histogram' ] }
 
 ##
 # @StatsUnit:
 #
 # Enumeration of unit of measurement for statistics
 #
 # @bytes: stat reported in bytes.
 # @seconds: stat reported in seconds.
 # @cycles: stat reported in clock cycles.
 # @boolean: stat is a boolean value.
 #
 # Since: 7.1
 ##
 { 'enum' : 'StatsUnit',
   'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] }
 
 ##
 # @StatsProvider:
 #
 # Enumeration of statistics providers.
 #
 # Since: 7.1
 ##
 { 'enum': 'StatsProvider',
   'data': [ 'kvm' ] }
 
 ##
 # @StatsTarget:
 #
 # The kinds of objects on which one can request statistics.
 #
 # @vm: statistics that apply to the entire virtual machine or
 #      the entire QEMU process.
 #
 # @vcpu: statistics that apply to a single virtual CPU.
 #
 # Since: 7.1
 ##
 { 'enum': 'StatsTarget',
   'data': [ 'vm', 'vcpu' ] }
 
 ##
 # @StatsRequest:
 #
 # Indicates a set of statistics that should be returned by query-stats.
 #
 # @provider: provider for which to return statistics.
 
 # @names: statistics to be returned (all if omitted).
 #
 # Since: 7.1
 ##
 { 'struct': 'StatsRequest',
   'data': { 'provider': 'StatsProvider',
             '*names': [ 'str' ] } }
 
 ##
 # @StatsVCPUFilter:
 #
 # @vcpus: list of QOM paths for the desired vCPU objects.
 #
 # Since: 7.1
 ##
 { 'struct': 'StatsVCPUFilter',
   'data': { '*vcpus': [ 'str' ] } }
 
 ##
 # @StatsFilter:
 #
 # The arguments to the query-stats command; specifies a target for which to
 # request statistics and optionally the required subset of information for
 # that target:
 # - which vCPUs to request statistics for
 # - which providers to request statistics from
 # - which named values to return within each provider
 #
 # Since: 7.1
 ##
 { 'union': 'StatsFilter',
   'base': {
       'target': 'StatsTarget',
       '*providers': [ 'StatsRequest' ] },
   'discriminator': 'target',
   'data': { 'vcpu': 'StatsVCPUFilter' } }
 
 ##
 # @StatsValue:
 #
 # @scalar: single unsigned 64-bit integers.
 # @list: list of unsigned 64-bit integers (used for histograms).
 #
 # Since: 7.1
 ##
 { 'alternate': 'StatsValue',
   'data': { 'scalar': 'uint64',
             'boolean': 'bool',
             'list': [ 'uint64' ] } }
 
 ##
 # @Stats:
 #
 # @name: name of stat.
 # @value: stat value.
 #
 # Since: 7.1
 ##
 { 'struct': 'Stats',
   'data': { 'name': 'str',
             'value' : 'StatsValue' } }
 
 ##
 # @StatsResult:
 #
 # @provider: provider for this set of statistics.
 #
 # @qom-path: Path to the object for which the statistics are returned,
 #            if the object is exposed in the QOM tree
 #
 # @stats: list of statistics.
 #
 # Since: 7.1
 ##
 { 'struct': 'StatsResult',
   'data': { 'provider': 'StatsProvider',
             '*qom-path': 'str',
             'stats': [ 'Stats' ] } }
 
 ##
 # @query-stats:
 #
 # Return runtime-collected statistics for objects such as the
 # VM or its vCPUs.
 #
 # The arguments are a StatsFilter and specify the provider and objects
 # to return statistics about.
 #
 # Returns: a list of StatsResult, one for each provider and object
 #          (e.g., for each vCPU).
 #
 # Since: 7.1
 ##
 { 'command': 'query-stats',
   'data': 'StatsFilter',
   'boxed': true,
   'returns': [ 'StatsResult' ] }
 
 ##
 # @StatsSchemaValue:
 #
 # Schema for a single statistic.
 #
 # @name: name of the statistic; each element of the schema is uniquely
 #        identified by a target, a provider (both available in @StatsSchema)
 #        and the name.
 #
 # @type: kind of statistic.
 #
 # @unit: basic unit of measure for the statistic; if missing, the statistic
 #        is a simple number or counter.
 #
 # @base: base for the multiple of @unit in which the statistic is measured.
 #        Only present if @exponent is non-zero; @base and @exponent together
 #        form a SI prefix (e.g., _nano-_ for ``base=10`` and ``exponent=-9``)
 #        or IEC binary prefix (e.g. _kibi-_ for ``base=2`` and ``exponent=10``)
 #
 # @exponent: exponent for the multiple of @unit in which the statistic is
 #            expressed, or 0 for the basic unit
 #
 # @bucket-size: Present when @type is "linear-histogram", contains the width
 #               of each bucket of the histogram.
 #
 # Since: 7.1
 ##
 { 'struct': 'StatsSchemaValue',
   'data': { 'name': 'str',
             'type': 'StatsType',
             '*unit': 'StatsUnit',
             '*base': 'int8',
             'exponent': 'int16',
             '*bucket-size': 'uint32' } }
 
 ##
 # @StatsSchema:
 #
 # Schema for all available statistics for a provider and target.
 #
 # @provider: provider for this set of statistics.
 #
 # @target: the kind of object that can be queried through the provider.
 #
 # @stats: list of statistics.
 #
 # Since: 7.1
 ##
 { 'struct': 'StatsSchema',
   'data': { 'provider': 'StatsProvider',
             'target': 'StatsTarget',
             'stats': [ 'StatsSchemaValue' ] } }
 
 ##
 # @query-stats-schemas:
 #
 # Return the schema for all available runtime-collected statistics.
 #
 # Note: runtime-collected statistics and their names fall outside QEMU's usual
 #       deprecation policies.  QEMU will try to keep the set of available data
 #       stable, together with their names, but will not guarantee stability
 #       at all costs; the same is true of providers that source statistics
 #       externally, e.g. from Linux.  For example, if the same value is being
 #       tracked with different names on different architectures or by different
 #       providers, one of them might be renamed.  A statistic might go away if
 #       an algorithm is changed or some code is removed; changing a default
 #       might cause previously useful statistics to always report 0.  Such
 #       changes, however, are expected to be rare.
 #
 # Since: 7.1
 ##
 { 'command': 'query-stats-schemas',
   'data': { '*provider': 'StatsProvider' },
   'returns': [ 'StatsSchema' ] }