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