]>
Commit | Line | Data |
---|---|---|
b9f88dc0 MK |
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. | |
a937b6aa | 21 | # |
b9f88dc0 | 22 | # @instant: stat is instantaneous; value can increase or decrease. |
a937b6aa | 23 | # |
b9f88dc0 | 24 | # @peak: stat is the peak value; value can only increase. |
a937b6aa | 25 | # |
b9f88dc0 | 26 | # @linear-histogram: stat is a linear histogram. |
a937b6aa | 27 | # |
b9f88dc0 | 28 | # @log2-histogram: stat is a logarithmic histogram, with one bucket |
a937b6aa | 29 | # for each power of two. |
b9f88dc0 MK |
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. | |
a937b6aa | 43 | # |
b9f88dc0 | 44 | # @seconds: stat reported in seconds. |
a937b6aa | 45 | # |
b9f88dc0 | 46 | # @cycles: stat reported in clock cycles. |
a937b6aa | 47 | # |
1ca1a7ec | 48 | # @boolean: stat is a boolean value. |
b9f88dc0 MK |
49 | # |
50 | # Since: 7.1 | |
51 | ## | |
52 | { 'enum' : 'StatsUnit', | |
1ca1a7ec | 53 | 'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] } |
b9f88dc0 MK |
54 | |
55 | ## | |
56 | # @StatsProvider: | |
57 | # | |
58 | # Enumeration of statistics providers. | |
59 | # | |
f2b90109 ZP |
60 | # @kvm: since 7.1 |
61 | # | |
62 | # @cryptodev: since 8.0 | |
63 | # | |
b9f88dc0 MK |
64 | # Since: 7.1 |
65 | ## | |
66 | { 'enum': 'StatsProvider', | |
f2b90109 | 67 | 'data': [ 'kvm', 'cryptodev' ] } |
b9f88dc0 MK |
68 | |
69 | ## | |
70 | # @StatsTarget: | |
71 | # | |
72 | # The kinds of objects on which one can request statistics. | |
73 | # | |
a937b6aa MA |
74 | # @vm: statistics that apply to the entire virtual machine or the |
75 | # entire QEMU process. | |
b9f88dc0 MK |
76 | # |
77 | # @vcpu: statistics that apply to a single virtual CPU. | |
78 | # | |
94546de1 | 79 | # @cryptodev: statistics that apply to a crypto device (since 8.0) |
f2b90109 | 80 | # |
b9f88dc0 MK |
81 | # Since: 7.1 |
82 | ## | |
83 | { 'enum': 'StatsTarget', | |
f2b90109 | 84 | 'data': [ 'vm', 'vcpu', 'cryptodev' ] } |
b9f88dc0 | 85 | |
068cc51d PB |
86 | ## |
87 | # @StatsRequest: | |
88 | # | |
a937b6aa MA |
89 | # Indicates a set of statistics that should be returned by |
90 | # query-stats. | |
068cc51d PB |
91 | # |
92 | # @provider: provider for which to return statistics. | |
a937b6aa | 93 | # |
cf7405bc | 94 | # @names: statistics to be returned (all if omitted). |
068cc51d PB |
95 | # |
96 | # Since: 7.1 | |
97 | ## | |
98 | { 'struct': 'StatsRequest', | |
cf7405bc PB |
99 | 'data': { 'provider': 'StatsProvider', |
100 | '*names': [ 'str' ] } } | |
068cc51d | 101 | |
467ef823 PB |
102 | ## |
103 | # @StatsVCPUFilter: | |
104 | # | |
105 | # @vcpus: list of QOM paths for the desired vCPU objects. | |
106 | # | |
107 | # Since: 7.1 | |
108 | ## | |
109 | { 'struct': 'StatsVCPUFilter', | |
110 | 'data': { '*vcpus': [ 'str' ] } } | |
111 | ||
b9f88dc0 MK |
112 | ## |
113 | # @StatsFilter: | |
114 | # | |
a937b6aa MA |
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: | |
c1101028 | 118 | # |
467ef823 | 119 | # - which vCPUs to request statistics for |
068cc51d | 120 | # - which providers to request statistics from |
cf7405bc | 121 | # - which named values to return within each provider |
b9f88dc0 MK |
122 | # |
123 | # Since: 7.1 | |
124 | ## | |
467ef823 | 125 | { 'union': 'StatsFilter', |
068cc51d PB |
126 | 'base': { |
127 | 'target': 'StatsTarget', | |
128 | '*providers': [ 'StatsRequest' ] }, | |
467ef823 PB |
129 | 'discriminator': 'target', |
130 | 'data': { 'vcpu': 'StatsVCPUFilter' } } | |
b9f88dc0 MK |
131 | |
132 | ## | |
133 | # @StatsValue: | |
134 | # | |
135 | # @scalar: single unsigned 64-bit integers. | |
a937b6aa | 136 | # |
b9f88dc0 MK |
137 | # @list: list of unsigned 64-bit integers (used for histograms). |
138 | # | |
139 | # Since: 7.1 | |
140 | ## | |
141 | { 'alternate': 'StatsValue', | |
142 | 'data': { 'scalar': 'uint64', | |
1ca1a7ec | 143 | 'boolean': 'bool', |
b9f88dc0 MK |
144 | 'list': [ 'uint64' ] } } |
145 | ||
146 | ## | |
147 | # @Stats: | |
148 | # | |
149 | # @name: name of stat. | |
a937b6aa | 150 | # |
b9f88dc0 MK |
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, | |
a937b6aa | 165 | # if the object is exposed in the QOM tree |
b9f88dc0 MK |
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 | # | |
a937b6aa MA |
179 | # Return runtime-collected statistics for objects such as the VM or |
180 | # its vCPUs. | |
b9f88dc0 MK |
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 | |
a937b6aa | 186 | # (e.g., for each vCPU). |
b9f88dc0 MK |
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 | |
a937b6aa MA |
201 | # identified by a target, a provider (both available in |
202 | # @StatsSchema) and the name. | |
b9f88dc0 MK |
203 | # |
204 | # @type: kind of statistic. | |
205 | # | |
a937b6aa MA |
206 | # @unit: basic unit of measure for the statistic; if missing, the |
207 | # statistic is a simple number or counter. | |
b9f88dc0 | 208 | # |
a937b6aa MA |
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``) | |
b9f88dc0 | 214 | # |
a937b6aa MA |
215 | # @exponent: exponent for the multiple of @unit in which the statistic |
216 | # is expressed, or 0 for the basic unit | |
b9f88dc0 | 217 | # |
a937b6aa MA |
218 | # @bucket-size: Present when @type is "linear-histogram", contains the |
219 | # width of each bucket of the histogram. | |
b9f88dc0 MK |
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 | # | |
a937b6aa MA |
238 | # @target: the kind of object that can be queried through the |
239 | # provider. | |
b9f88dc0 MK |
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 | # | |
a937b6aa MA |
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. | |
b9f88dc0 MK |
266 | # |
267 | # Since: 7.1 | |
268 | ## | |
269 | { 'command': 'query-stats-schemas', | |
068cc51d | 270 | 'data': { '*provider': 'StatsProvider' }, |
b9f88dc0 | 271 | 'returns': [ 'StatsSchema' ] } |