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