# -*- 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.
#
# Since: 7.1
##
{ 'enum' : 'StatsUnit',
'data' : [ 'bytes', 'seconds', 'cycles' ] }
##
# @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.
#
# Since: 7.1
##
{ 'struct': 'StatsRequest',
'data': { 'provider': 'StatsProvider' } }
##
# @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
#
# 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',
'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' ] }
