| 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 | # ********** |
| 13 | # Statistics |
| 14 | # ********** |
| 15 | ## |
| 16 | |
| 17 | ## |
| 18 | # @StatsType: |
| 19 | # |
| 20 | # Enumeration of statistics types |
| 21 | # |
| 22 | # @cumulative: stat is cumulative; value can only increase. |
| 23 | # |
| 24 | # @instant: stat is instantaneous; value can increase or decrease. |
| 25 | # |
| 26 | # @peak: stat is the peak value; value can only increase. |
| 27 | # |
| 28 | # @linear-histogram: stat is a linear histogram. |
| 29 | # |
| 30 | # @log2-histogram: stat is a logarithmic histogram, with one bucket |
| 31 | # for each power of two. |
| 32 | # |
| 33 | # Since: 7.1 |
| 34 | ## |
| 35 | { 'enum' : 'StatsType', |
| 36 | 'data' : [ 'cumulative', 'instant', 'peak', 'linear-histogram', |
| 37 | 'log2-histogram' ] } |
| 38 | |
| 39 | ## |
| 40 | # @StatsUnit: |
| 41 | # |
| 42 | # Enumeration of unit of measurement for statistics |
| 43 | # |
| 44 | # @bytes: stat reported in bytes. |
| 45 | # |
| 46 | # @seconds: stat reported in seconds. |
| 47 | # |
| 48 | # @cycles: stat reported in clock cycles. |
| 49 | # |
| 50 | # @boolean: stat is a boolean value. |
| 51 | # |
| 52 | # Since: 7.1 |
| 53 | ## |
| 54 | { 'enum' : 'StatsUnit', |
| 55 | 'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] } |
| 56 | |
| 57 | ## |
| 58 | # @StatsProvider: |
| 59 | # |
| 60 | # Enumeration of statistics providers. |
| 61 | # |
| 62 | # @kvm: since 7.1 |
| 63 | # |
| 64 | # @cryptodev: since 8.0 |
| 65 | # |
| 66 | # Since: 7.1 |
| 67 | ## |
| 68 | { 'enum': 'StatsProvider', |
| 69 | 'data': [ 'kvm', 'cryptodev' ] } |
| 70 | |
| 71 | ## |
| 72 | # @StatsTarget: |
| 73 | # |
| 74 | # The kinds of objects on which one can request statistics. |
| 75 | # |
| 76 | # @vm: statistics that apply to the entire virtual machine or the |
| 77 | # entire QEMU process. |
| 78 | # |
| 79 | # @vcpu: statistics that apply to a single virtual CPU. |
| 80 | # |
| 81 | # @cryptodev: statistics that apply to a crypto device (since 8.0) |
| 82 | # |
| 83 | # Since: 7.1 |
| 84 | ## |
| 85 | { 'enum': 'StatsTarget', |
| 86 | 'data': [ 'vm', 'vcpu', 'cryptodev' ] } |
| 87 | |
| 88 | ## |
| 89 | # @StatsRequest: |
| 90 | # |
| 91 | # Indicates a set of statistics that should be returned by |
| 92 | # `query-stats`. |
| 93 | # |
| 94 | # @provider: provider for which to return statistics. |
| 95 | # |
| 96 | # @names: statistics to be returned (all if omitted). |
| 97 | # |
| 98 | # Since: 7.1 |
| 99 | ## |
| 100 | { 'struct': 'StatsRequest', |
| 101 | 'data': { 'provider': 'StatsProvider', |
| 102 | '*names': [ 'str' ] } } |
| 103 | |
| 104 | ## |
| 105 | # @StatsVCPUFilter: |
| 106 | # |
| 107 | # @vcpus: list of QOM paths for the desired vCPU objects. |
| 108 | # |
| 109 | # Since: 7.1 |
| 110 | ## |
| 111 | { 'struct': 'StatsVCPUFilter', |
| 112 | 'data': { '*vcpus': [ 'str' ] } } |
| 113 | |
| 114 | ## |
| 115 | # @StatsFilter: |
| 116 | # |
| 117 | # The arguments to the `query-stats` command; specifies a target for |
| 118 | # which to request statistics and optionally the required subset of |
| 119 | # information for that target. |
| 120 | # |
| 121 | # @target: the kind of objects to query. Note that each possible |
| 122 | # target may enable additional filtering options |
| 123 | # |
| 124 | # @providers: which providers to request statistics from, and |
| 125 | # optionally which named values to return within each provider |
| 126 | # |
| 127 | # Since: 7.1 |
| 128 | ## |
| 129 | { 'union': 'StatsFilter', |
| 130 | 'base': { |
| 131 | 'target': 'StatsTarget', |
| 132 | '*providers': [ 'StatsRequest' ] }, |
| 133 | 'discriminator': 'target', |
| 134 | 'data': { 'vcpu': 'StatsVCPUFilter' } } |
| 135 | |
| 136 | ## |
| 137 | # @StatsValue: |
| 138 | # |
| 139 | # @scalar: single unsigned 64-bit integers. |
| 140 | # |
| 141 | # @boolean: single boolean value. |
| 142 | # |
| 143 | # @list: list of unsigned 64-bit integers (used for histograms). |
| 144 | # |
| 145 | # Since: 7.1 |
| 146 | ## |
| 147 | { 'alternate': 'StatsValue', |
| 148 | 'data': { 'scalar': 'uint64', |
| 149 | 'boolean': 'bool', |
| 150 | 'list': [ 'uint64' ] } } |
| 151 | |
| 152 | ## |
| 153 | # @Stats: |
| 154 | # |
| 155 | # @name: name of stat. |
| 156 | # |
| 157 | # @value: stat value. |
| 158 | # |
| 159 | # Since: 7.1 |
| 160 | ## |
| 161 | { 'struct': 'Stats', |
| 162 | 'data': { 'name': 'str', |
| 163 | 'value' : 'StatsValue' } } |
| 164 | |
| 165 | ## |
| 166 | # @StatsResult: |
| 167 | # |
| 168 | # @provider: provider for this set of statistics. |
| 169 | # |
| 170 | # @qom-path: Path to the object for which the statistics are returned, |
| 171 | # if the object is exposed in the QOM tree |
| 172 | # |
| 173 | # @stats: list of statistics. |
| 174 | # |
| 175 | # Since: 7.1 |
| 176 | ## |
| 177 | { 'struct': 'StatsResult', |
| 178 | 'data': { 'provider': 'StatsProvider', |
| 179 | '*qom-path': 'str', |
| 180 | 'stats': [ 'Stats' ] } } |
| 181 | |
| 182 | ## |
| 183 | # @query-stats: |
| 184 | # |
| 185 | # Return runtime-collected statistics for objects such as the VM or |
| 186 | # its vCPUs. |
| 187 | # |
| 188 | # The arguments are a `StatsFilter` and specify the provider and |
| 189 | # objects to return statistics about. |
| 190 | # |
| 191 | # Returns: a list of statistics, one for each provider and object |
| 192 | # (e.g., for each vCPU). |
| 193 | # |
| 194 | # Since: 7.1 |
| 195 | ## |
| 196 | { 'command': 'query-stats', |
| 197 | 'data': 'StatsFilter', |
| 198 | 'boxed': true, |
| 199 | 'returns': [ 'StatsResult' ] } |
| 200 | |
| 201 | ## |
| 202 | # @StatsSchemaValue: |
| 203 | # |
| 204 | # Schema for a single statistic. |
| 205 | # |
| 206 | # @name: name of the statistic; each element of the schema is uniquely |
| 207 | # identified by a target, a provider (both available in |
| 208 | # `StatsSchema`) and the name. |
| 209 | # |
| 210 | # @type: kind of statistic. |
| 211 | # |
| 212 | # @unit: basic unit of measure for the statistic; if missing, the |
| 213 | # statistic is a simple number or counter. |
| 214 | # |
| 215 | # @base: base for the multiple of @unit in which the statistic is |
| 216 | # measured. Only present if @exponent is non-zero; @base and |
| 217 | # @exponent together form a SI prefix (e.g., _nano-_ for |
| 218 | # ``base=10`` and ``exponent=-9``) or IEC binary prefix (e.g. |
| 219 | # _kibi-_ for ``base=2`` and ``exponent=10``) |
| 220 | # |
| 221 | # @exponent: exponent for the multiple of @unit in which the statistic |
| 222 | # is expressed, or 0 for the basic unit |
| 223 | # |
| 224 | # @bucket-size: Present when @type is "linear-histogram", contains the |
| 225 | # width of each bucket of the histogram. |
| 226 | # |
| 227 | # Since: 7.1 |
| 228 | ## |
| 229 | { 'struct': 'StatsSchemaValue', |
| 230 | 'data': { 'name': 'str', |
| 231 | 'type': 'StatsType', |
| 232 | '*unit': 'StatsUnit', |
| 233 | '*base': 'int8', |
| 234 | 'exponent': 'int16', |
| 235 | '*bucket-size': 'uint32' } } |
| 236 | |
| 237 | ## |
| 238 | # @StatsSchema: |
| 239 | # |
| 240 | # Schema for all available statistics for a provider and target. |
| 241 | # |
| 242 | # @provider: provider for this set of statistics. |
| 243 | # |
| 244 | # @target: the kind of object that can be queried through the |
| 245 | # provider. |
| 246 | # |
| 247 | # @stats: list of statistics. |
| 248 | # |
| 249 | # Since: 7.1 |
| 250 | ## |
| 251 | { 'struct': 'StatsSchema', |
| 252 | 'data': { 'provider': 'StatsProvider', |
| 253 | 'target': 'StatsTarget', |
| 254 | 'stats': [ 'StatsSchemaValue' ] } } |
| 255 | |
| 256 | ## |
| 257 | # @query-stats-schemas: |
| 258 | # |
| 259 | # Return the schema for all available runtime-collected statistics. |
| 260 | # |
| 261 | # @provider: a provider to restrict the query to. |
| 262 | # |
| 263 | # .. note:: Runtime-collected statistics and their names fall outside |
| 264 | # QEMU's usual deprecation policies. QEMU will try to keep the set |
| 265 | # of available data stable, together with their names, but will not |
| 266 | # guarantee stability at all costs; the same is true of providers |
| 267 | # that source statistics externally, e.g. from Linux. For example, |
| 268 | # if the same value is being tracked with different names on |
| 269 | # different architectures or by different providers, one of them |
| 270 | # might be renamed. A statistic might go away if an algorithm is |
| 271 | # changed or some code is removed; changing a default might cause |
| 272 | # previously useful statistics to always report 0. Such changes, |
| 273 | # however, are expected to be rare. |
| 274 | # |
| 275 | # Since: 7.1 |
| 276 | ## |
| 277 | { 'command': 'query-stats-schemas', |
| 278 | 'data': { '*provider': 'StatsProvider' }, |
| 279 | 'returns': [ 'StatsSchema' ] } |