]>
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. | |
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. | |
1ca1a7ec | 41 | # @boolean: stat is a boolean value. |
b9f88dc0 MK |
42 | # |
43 | # Since: 7.1 | |
44 | ## | |
45 | { 'enum' : 'StatsUnit', | |
1ca1a7ec | 46 | 'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] } |
b9f88dc0 MK |
47 | |
48 | ## | |
49 | # @StatsProvider: | |
50 | # | |
51 | # Enumeration of statistics providers. | |
52 | # | |
f2b90109 ZP |
53 | # @kvm: since 7.1 |
54 | # | |
55 | # @cryptodev: since 8.0 | |
56 | # | |
b9f88dc0 MK |
57 | # Since: 7.1 |
58 | ## | |
59 | { 'enum': 'StatsProvider', | |
f2b90109 | 60 | 'data': [ 'kvm', 'cryptodev' ] } |
b9f88dc0 MK |
61 | |
62 | ## | |
63 | # @StatsTarget: | |
64 | # | |
65 | # The kinds of objects on which one can request statistics. | |
66 | # | |
67 | # @vm: statistics that apply to the entire virtual machine or | |
68 | # the entire QEMU process. | |
69 | # | |
70 | # @vcpu: statistics that apply to a single virtual CPU. | |
71 | # | |
f2b90109 ZP |
72 | # @cryptodev: statistics that apply to a crypto device. since 8.0 |
73 | # | |
b9f88dc0 MK |
74 | # Since: 7.1 |
75 | ## | |
76 | { 'enum': 'StatsTarget', | |
f2b90109 | 77 | 'data': [ 'vm', 'vcpu', 'cryptodev' ] } |
b9f88dc0 | 78 | |
068cc51d PB |
79 | ## |
80 | # @StatsRequest: | |
81 | # | |
82 | # Indicates a set of statistics that should be returned by query-stats. | |
83 | # | |
84 | # @provider: provider for which to return statistics. | |
cf7405bc PB |
85 | |
86 | # @names: statistics to be returned (all if omitted). | |
068cc51d PB |
87 | # |
88 | # Since: 7.1 | |
89 | ## | |
90 | { 'struct': 'StatsRequest', | |
cf7405bc PB |
91 | 'data': { 'provider': 'StatsProvider', |
92 | '*names': [ 'str' ] } } | |
068cc51d | 93 | |
467ef823 PB |
94 | ## |
95 | # @StatsVCPUFilter: | |
96 | # | |
97 | # @vcpus: list of QOM paths for the desired vCPU objects. | |
98 | # | |
99 | # Since: 7.1 | |
100 | ## | |
101 | { 'struct': 'StatsVCPUFilter', | |
102 | 'data': { '*vcpus': [ 'str' ] } } | |
103 | ||
b9f88dc0 MK |
104 | ## |
105 | # @StatsFilter: | |
106 | # | |
107 | # The arguments to the query-stats command; specifies a target for which to | |
467ef823 PB |
108 | # request statistics and optionally the required subset of information for |
109 | # that target: | |
110 | # - which vCPUs to request statistics for | |
068cc51d | 111 | # - which providers to request statistics from |
cf7405bc | 112 | # - which named values to return within each provider |
b9f88dc0 MK |
113 | # |
114 | # Since: 7.1 | |
115 | ## | |
467ef823 | 116 | { 'union': 'StatsFilter', |
068cc51d PB |
117 | 'base': { |
118 | 'target': 'StatsTarget', | |
119 | '*providers': [ 'StatsRequest' ] }, | |
467ef823 PB |
120 | 'discriminator': 'target', |
121 | 'data': { 'vcpu': 'StatsVCPUFilter' } } | |
b9f88dc0 MK |
122 | |
123 | ## | |
124 | # @StatsValue: | |
125 | # | |
126 | # @scalar: single unsigned 64-bit integers. | |
127 | # @list: list of unsigned 64-bit integers (used for histograms). | |
128 | # | |
129 | # Since: 7.1 | |
130 | ## | |
131 | { 'alternate': 'StatsValue', | |
132 | 'data': { 'scalar': 'uint64', | |
1ca1a7ec | 133 | 'boolean': 'bool', |
b9f88dc0 MK |
134 | 'list': [ 'uint64' ] } } |
135 | ||
136 | ## | |
137 | # @Stats: | |
138 | # | |
139 | # @name: name of stat. | |
140 | # @value: stat value. | |
141 | # | |
142 | # Since: 7.1 | |
143 | ## | |
144 | { 'struct': 'Stats', | |
145 | 'data': { 'name': 'str', | |
146 | 'value' : 'StatsValue' } } | |
147 | ||
148 | ## | |
149 | # @StatsResult: | |
150 | # | |
151 | # @provider: provider for this set of statistics. | |
152 | # | |
153 | # @qom-path: Path to the object for which the statistics are returned, | |
154 | # if the object is exposed in the QOM tree | |
155 | # | |
156 | # @stats: list of statistics. | |
157 | # | |
158 | # Since: 7.1 | |
159 | ## | |
160 | { 'struct': 'StatsResult', | |
161 | 'data': { 'provider': 'StatsProvider', | |
162 | '*qom-path': 'str', | |
163 | 'stats': [ 'Stats' ] } } | |
164 | ||
165 | ## | |
166 | # @query-stats: | |
167 | # | |
168 | # Return runtime-collected statistics for objects such as the | |
169 | # VM or its vCPUs. | |
170 | # | |
171 | # The arguments are a StatsFilter and specify the provider and objects | |
172 | # to return statistics about. | |
173 | # | |
174 | # Returns: a list of StatsResult, one for each provider and object | |
175 | # (e.g., for each vCPU). | |
176 | # | |
177 | # Since: 7.1 | |
178 | ## | |
179 | { 'command': 'query-stats', | |
180 | 'data': 'StatsFilter', | |
181 | 'boxed': true, | |
182 | 'returns': [ 'StatsResult' ] } | |
183 | ||
184 | ## | |
185 | # @StatsSchemaValue: | |
186 | # | |
187 | # Schema for a single statistic. | |
188 | # | |
189 | # @name: name of the statistic; each element of the schema is uniquely | |
190 | # identified by a target, a provider (both available in @StatsSchema) | |
191 | # and the name. | |
192 | # | |
193 | # @type: kind of statistic. | |
194 | # | |
195 | # @unit: basic unit of measure for the statistic; if missing, the statistic | |
196 | # is a simple number or counter. | |
197 | # | |
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``) | |
202 | # | |
203 | # @exponent: exponent for the multiple of @unit in which the statistic is | |
204 | # expressed, or 0 for the basic unit | |
205 | # | |
206 | # @bucket-size: Present when @type is "linear-histogram", contains the width | |
207 | # of each bucket of the histogram. | |
208 | # | |
209 | # Since: 7.1 | |
210 | ## | |
211 | { 'struct': 'StatsSchemaValue', | |
212 | 'data': { 'name': 'str', | |
213 | 'type': 'StatsType', | |
214 | '*unit': 'StatsUnit', | |
215 | '*base': 'int8', | |
216 | 'exponent': 'int16', | |
217 | '*bucket-size': 'uint32' } } | |
218 | ||
219 | ## | |
220 | # @StatsSchema: | |
221 | # | |
222 | # Schema for all available statistics for a provider and target. | |
223 | # | |
224 | # @provider: provider for this set of statistics. | |
225 | # | |
226 | # @target: the kind of object that can be queried through the provider. | |
227 | # | |
228 | # @stats: list of statistics. | |
229 | # | |
230 | # Since: 7.1 | |
231 | ## | |
232 | { 'struct': 'StatsSchema', | |
233 | 'data': { 'provider': 'StatsProvider', | |
234 | 'target': 'StatsTarget', | |
235 | 'stats': [ 'StatsSchemaValue' ] } } | |
236 | ||
237 | ## | |
238 | # @query-stats-schemas: | |
239 | # | |
240 | # Return the schema for all available runtime-collected statistics. | |
241 | # | |
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. | |
252 | # | |
253 | # Since: 7.1 | |
254 | ## | |
255 | { 'command': 'query-stats-schemas', | |
068cc51d | 256 | 'data': { '*provider': 'StatsProvider' }, |
b9f88dc0 | 257 | 'returns': [ 'StatsSchema' ] } |