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