Re: [PATCH for 8.9.0] 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 filed

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(a)redhat.com&gt; --- docs/manpages/virsh.rst | 36 ++++++++++++++++++++++++++++++++++-- src/libvirt-domain.c | 26 +++++++++++++++++++++++++- tools/virsh-domain-monitor.c | 2 +- 3 files changed, 60 insertions(+), 4 deletions(-)