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