]> xenbits.xensource.com Git - libvirt.git/commit
Document caveats of 'VIR_DOMAIN_STATS_VM' group of statistics
authorPeter Krempa <pkrempa@redhat.com>
Tue, 1 Nov 2022 09:39:16 +0000 (10:39 +0100)
committerPeter Krempa <pkrempa@redhat.com>
Tue, 1 Nov 2022 10:56:00 +0000 (11:56 +0100)
commitc43718ef6794458daccc5876e576e0bbc1da6763
treea45820694d46e790e386a9b55d090a3251962292
parent06b31a2804711f953165d29028b59d212c874606
Document caveats of 'VIR_DOMAIN_STATS_VM' group of statistics

The original patches adding the functionality neglected to add any form
of documentation for the stats fields returned for this group.

The stats are directly converted from qemu's 'query-stats(-schema)' QMP
command without any further interpretation. The 'query-stats-schema' has
the following disclaimer:

 Note: runtime-collected statistics and their names fall outside QEMU's usual
       deprecation policies.  QEMU will try to keep the set of available data
       stable, together with their names, but will not guarantee stability
       at all costs; the same is true of providers that source statistics
       externally, e.g. from Linux.  For example, if the same value is being
       tracked with different names on different architectures or by different
       providers, one of them might be renamed.  A statistic might go away if
       an algorithm is changed or some code is removed; changing a default
       might cause previously useful statistics to always report 0.  Such
       changes, however, are expected to be rare.

Since libvirt is not doing any form of conversion of the stats we can't
meaningfully document any of the returned fields. At the same time we
can't even meaningfully provide any form of API stability for the field
names.

Modify the documentation for the 'VIR_DOMAIN_STATS_VM' group both in the
API docs and in the virsh man page to reflect that and disclaim any form
of stability guarantees we provide normally.

Fixes: 8c9e3dae142
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Jiri Denemark <jdenemar@redhat.com>
docs/manpages/virsh.rst
src/libvirt-domain.c
tools/virsh-domain-monitor.c