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