[PATCH for 8.9.0] Document caveats of 'VIR_DOMAIN_STATS_VM' group of statistics

[Ján Tomko]

On a Tuesday in 2022, Peter Krempa wrote:
>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

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

Reviewed-by: Ján Tomko <jtomko at redhat.com>

Jano