4 # Copyright (c) 2022 Oracle and/or its affiliates.
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.
9 # SPDX-License-Identifier: GPL-2.0-or-later
18 # Enumeration of statistics types
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.
29 { 'enum' : 'StatsType',
30 'data' : [ 'cumulative', 'instant', 'peak', 'linear-histogram',
36 # Enumeration of unit of measurement for statistics
38 # @bytes: stat reported in bytes.
39 # @seconds: stat reported in seconds.
40 # @cycles: stat reported in clock cycles.
41 # @boolean: stat is a boolean value.
45 { 'enum' : 'StatsUnit',
46 'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] }
51 # Enumeration of statistics providers.
55 # @cryptodev: since 8.0
59 { 'enum': 'StatsProvider',
60 'data': [ 'kvm', 'cryptodev' ] }
65 # The kinds of objects on which one can request statistics.
67 # @vm: statistics that apply to the entire virtual machine or
68 # the entire QEMU process.
70 # @vcpu: statistics that apply to a single virtual CPU.
72 # @cryptodev: statistics that apply to a crypto device. since 8.0
76 { 'enum': 'StatsTarget',
77 'data': [ 'vm', 'vcpu', 'cryptodev' ] }
82 # Indicates a set of statistics that should be returned by query-stats.
84 # @provider: provider for which to return statistics.
86 # @names: statistics to be returned (all if omitted).
90 { 'struct': 'StatsRequest',
91 'data': { 'provider': 'StatsProvider',
92 '*names': [ 'str' ] } }
97 # @vcpus: list of QOM paths for the desired vCPU objects.
101 { 'struct': 'StatsVCPUFilter',
102 'data': { '*vcpus': [ 'str' ] } }
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
110 # - which vCPUs to request statistics for
111 # - which providers to request statistics from
112 # - which named values to return within each provider
116 { 'union': 'StatsFilter',
118 'target': 'StatsTarget',
119 '*providers': [ 'StatsRequest' ] },
120 'discriminator': 'target',
121 'data': { 'vcpu': 'StatsVCPUFilter' } }
126 # @scalar: single unsigned 64-bit integers.
127 # @list: list of unsigned 64-bit integers (used for histograms).
131 { 'alternate': 'StatsValue',
132 'data': { 'scalar': 'uint64',
134 'list': [ 'uint64' ] } }
139 # @name: name of stat.
140 # @value: stat value.
145 'data': { 'name': 'str',
146 'value' : 'StatsValue' } }
151 # @provider: provider for this set of statistics.
153 # @qom-path: Path to the object for which the statistics are returned,
154 # if the object is exposed in the QOM tree
156 # @stats: list of statistics.
160 { 'struct': 'StatsResult',
161 'data': { 'provider': 'StatsProvider',
163 'stats': [ 'Stats' ] } }
168 # Return runtime-collected statistics for objects such as the
171 # The arguments are a StatsFilter and specify the provider and objects
172 # to return statistics about.
174 # Returns: a list of StatsResult, one for each provider and object
175 # (e.g., for each vCPU).
179 { 'command': 'query-stats',
180 'data': 'StatsFilter',
182 'returns': [ 'StatsResult' ] }
187 # Schema for a single statistic.
189 # @name: name of the statistic; each element of the schema is uniquely
190 # identified by a target, a provider (both available in @StatsSchema)
193 # @type: kind of statistic.
195 # @unit: basic unit of measure for the statistic; if missing, the statistic
196 # is a simple number or counter.
198 # @base: base for the multiple of @unit in which the statistic is measured.
199 # Only present if @exponent is non-zero; @base and @exponent together
200 # form a SI prefix (e.g., _nano-_ for ``base=10`` and ``exponent=-9``)
201 # or IEC binary prefix (e.g. _kibi-_ for ``base=2`` and ``exponent=10``)
203 # @exponent: exponent for the multiple of @unit in which the statistic is
204 # expressed, or 0 for the basic unit
206 # @bucket-size: Present when @type is "linear-histogram", contains the width
207 # of each bucket of the histogram.
211 { 'struct': 'StatsSchemaValue',
212 'data': { 'name': 'str',
214 '*unit': 'StatsUnit',
217 '*bucket-size': 'uint32' } }
222 # Schema for all available statistics for a provider and target.
224 # @provider: provider for this set of statistics.
226 # @target: the kind of object that can be queried through the provider.
228 # @stats: list of statistics.
232 { 'struct': 'StatsSchema',
233 'data': { 'provider': 'StatsProvider',
234 'target': 'StatsTarget',
235 'stats': [ 'StatsSchemaValue' ] } }
238 # @query-stats-schemas:
240 # Return the schema for all available runtime-collected statistics.
242 # Note: runtime-collected statistics and their names fall outside QEMU's usual
243 # deprecation policies. QEMU will try to keep the set of available data
244 # stable, together with their names, but will not guarantee stability
245 # at all costs; the same is true of providers that source statistics
246 # externally, e.g. from Linux. For example, if the same value is being
247 # tracked with different names on different architectures or by different
248 # providers, one of them might be renamed. A statistic might go away if
249 # an algorithm is changed or some code is removed; changing a default
250 # might cause previously useful statistics to always report 0. Such
251 # changes, however, are expected to be rare.
255 { 'command': 'query-stats-schemas',
256 'data': { '*provider': 'StatsProvider' },
257 'returns': [ 'StatsSchema' ] }