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