]>
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 | |
1de75953 | 117 | # information for that target. |
c1101028 | 118 | # |
1de75953 PB |
119 | # @target: the kind of objects to query. Note that each possible |
120 | # target may enable additional filtering options | |
b9f88dc0 | 121 | # |
1de75953 PB |
122 | # @providers: which providers to request statistics from, and optionally |
123 | # which named values to return within each provider | |
89a2273b | 124 | # |
b9f88dc0 MK |
125 | # Since: 7.1 |
126 | ## | |
467ef823 | 127 | { 'union': 'StatsFilter', |
068cc51d PB |
128 | 'base': { |
129 | 'target': 'StatsTarget', | |
130 | '*providers': [ 'StatsRequest' ] }, | |
467ef823 PB |
131 | 'discriminator': 'target', |
132 | 'data': { 'vcpu': 'StatsVCPUFilter' } } | |
b9f88dc0 MK |
133 | |
134 | ## | |
135 | # @StatsValue: | |
136 | # | |
137 | # @scalar: single unsigned 64-bit integers. | |
a937b6aa | 138 | # |
1de75953 PB |
139 | # @boolean: single boolean value. |
140 | # | |
b9f88dc0 MK |
141 | # @list: list of unsigned 64-bit integers (used for histograms). |
142 | # | |
143 | # Since: 7.1 | |
144 | ## | |
145 | { 'alternate': 'StatsValue', | |
146 | 'data': { 'scalar': 'uint64', | |
1ca1a7ec | 147 | 'boolean': 'bool', |
b9f88dc0 MK |
148 | 'list': [ 'uint64' ] } } |
149 | ||
150 | ## | |
151 | # @Stats: | |
152 | # | |
153 | # @name: name of stat. | |
a937b6aa | 154 | # |
b9f88dc0 MK |
155 | # @value: stat value. |
156 | # | |
157 | # Since: 7.1 | |
158 | ## | |
159 | { 'struct': 'Stats', | |
160 | 'data': { 'name': 'str', | |
161 | 'value' : 'StatsValue' } } | |
162 | ||
163 | ## | |
164 | # @StatsResult: | |
165 | # | |
166 | # @provider: provider for this set of statistics. | |
167 | # | |
168 | # @qom-path: Path to the object for which the statistics are returned, | |
a937b6aa | 169 | # if the object is exposed in the QOM tree |
b9f88dc0 MK |
170 | # |
171 | # @stats: list of statistics. | |
172 | # | |
173 | # Since: 7.1 | |
174 | ## | |
175 | { 'struct': 'StatsResult', | |
176 | 'data': { 'provider': 'StatsProvider', | |
177 | '*qom-path': 'str', | |
178 | 'stats': [ 'Stats' ] } } | |
179 | ||
180 | ## | |
181 | # @query-stats: | |
182 | # | |
a937b6aa MA |
183 | # Return runtime-collected statistics for objects such as the VM or |
184 | # its vCPUs. | |
b9f88dc0 MK |
185 | # |
186 | # The arguments are a StatsFilter and specify the provider and objects | |
187 | # to return statistics about. | |
188 | # | |
189 | # Returns: a list of StatsResult, one for each provider and object | |
a937b6aa | 190 | # (e.g., for each vCPU). |
b9f88dc0 MK |
191 | # |
192 | # Since: 7.1 | |
193 | ## | |
194 | { 'command': 'query-stats', | |
195 | 'data': 'StatsFilter', | |
196 | 'boxed': true, | |
197 | 'returns': [ 'StatsResult' ] } | |
198 | ||
199 | ## | |
200 | # @StatsSchemaValue: | |
201 | # | |
202 | # Schema for a single statistic. | |
203 | # | |
204 | # @name: name of the statistic; each element of the schema is uniquely | |
a937b6aa MA |
205 | # identified by a target, a provider (both available in |
206 | # @StatsSchema) and the name. | |
b9f88dc0 MK |
207 | # |
208 | # @type: kind of statistic. | |
209 | # | |
a937b6aa MA |
210 | # @unit: basic unit of measure for the statistic; if missing, the |
211 | # statistic is a simple number or counter. | |
b9f88dc0 | 212 | # |
a937b6aa MA |
213 | # @base: base for the multiple of @unit in which the statistic is |
214 | # measured. Only present if @exponent is non-zero; @base and | |
215 | # @exponent together form a SI prefix (e.g., _nano-_ for | |
216 | # ``base=10`` and ``exponent=-9``) or IEC binary prefix (e.g. | |
217 | # _kibi-_ for ``base=2`` and ``exponent=10``) | |
b9f88dc0 | 218 | # |
a937b6aa MA |
219 | # @exponent: exponent for the multiple of @unit in which the statistic |
220 | # is expressed, or 0 for the basic unit | |
b9f88dc0 | 221 | # |
a937b6aa MA |
222 | # @bucket-size: Present when @type is "linear-histogram", contains the |
223 | # width of each bucket of the histogram. | |
b9f88dc0 MK |
224 | # |
225 | # Since: 7.1 | |
226 | ## | |
227 | { 'struct': 'StatsSchemaValue', | |
228 | 'data': { 'name': 'str', | |
229 | 'type': 'StatsType', | |
230 | '*unit': 'StatsUnit', | |
231 | '*base': 'int8', | |
232 | 'exponent': 'int16', | |
233 | '*bucket-size': 'uint32' } } | |
234 | ||
235 | ## | |
236 | # @StatsSchema: | |
237 | # | |
238 | # Schema for all available statistics for a provider and target. | |
239 | # | |
240 | # @provider: provider for this set of statistics. | |
241 | # | |
a937b6aa MA |
242 | # @target: the kind of object that can be queried through the |
243 | # provider. | |
b9f88dc0 MK |
244 | # |
245 | # @stats: list of statistics. | |
246 | # | |
247 | # Since: 7.1 | |
248 | ## | |
249 | { 'struct': 'StatsSchema', | |
250 | 'data': { 'provider': 'StatsProvider', | |
251 | 'target': 'StatsTarget', | |
252 | 'stats': [ 'StatsSchemaValue' ] } } | |
253 | ||
254 | ## | |
255 | # @query-stats-schemas: | |
256 | # | |
257 | # Return the schema for all available runtime-collected statistics. | |
258 | # | |
1de75953 PB |
259 | # @provider: a provider to restrict the query to. |
260 | # | |
a937b6aa MA |
261 | # Note: runtime-collected statistics and their names fall outside |
262 | # QEMU's usual deprecation policies. QEMU will try to keep the | |
263 | # set of available data stable, together with their names, but | |
264 | # will not guarantee stability at all costs; the same is true of | |
265 | # providers that source statistics externally, e.g. from Linux. | |
266 | # For example, if the same value is being tracked with different | |
267 | # names on different architectures or by different providers, one | |
268 | # of them might be renamed. A statistic might go away if an | |
269 | # algorithm is changed or some code is removed; changing a default | |
270 | # might cause previously useful statistics to always report 0. | |
271 | # Such changes, however, are expected to be rare. | |
b9f88dc0 MK |
272 | # |
273 | # Since: 7.1 | |
274 | ## | |
275 | { 'command': 'query-stats-schemas', | |
068cc51d | 276 | 'data': { '*provider': 'StatsProvider' }, |
b9f88dc0 | 277 | 'returns': [ 'StatsSchema' ] } |