src: document that no constants are provided for custom VM stats

Contrary to most APIs returning typed parameters, there are no constants
defined for the domain stats data keys. This is was because many of the
keys needs to be dynamically constructed using one or more array index
values.

It is possible to define constants while still supporting dynamic
array indexes by simply defining the prefixes and suffixes as constants.
The consuming code can then combine the constants with array index
value.

With this approach, it is practical to add constants for the domain stats
API keys.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index f2d313a76bbb66a9f2dcba2739a5701ef30aabee..8c86bd8f9480d5b84e955b5f667509db9c0e2be0 100644 (file)
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -3918,6 +3918,18 @@ struct _virDomainStatsRecord {
  */
 # define VIR_DOMAIN_STATS_DIRTYRATE_VCPU_SUFFIX_MEGABYTES_PER_SECOND ".megabytes_per_second"
 
+
+/**
+ * VIR_DOMAIN_STATS_VM_PREFIX:
+ *
+ * Concatenate the prefix, a hypervisor specific custom stats name and one
+ * of the VIR_DOMAIN_STATS_CUSTOM_TYPE_* constants to form a complete
+ * parameter name
+ *
+ * Since: 11.2.0
+ */
+# define VIR_DOMAIN_STATS_VM_PREFIX "vm."
+
 /**
  * virDomainStatsTypes:
  *

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 481a1833de9bfd21f227e9d43b48bff108b855fb..5bb9f3895e243dd2b0f64ebd48df349524eb577a 100644 (file)
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -12335,14 +12335,12 @@ virConnectGetDomainCapabilities(virConnectPtr conn,
  *
  *     "vm.$NAME.$TYPE"
  *
- *       $NAME - name of the statistics field provided by the hypervisor
- *
- *       $TYPE - Type of the value. The following types are returned:
- *          'cur' - current instant value
- *          'sum' - aggregate value
- *          'max' - peak value
+ *     Where $NAME is an arbitrary choice of the hypervisor driver, for
+ *     which no API constants are defined.
+ *     The $TYPE values are defined by VIR_DOMAIN_STATS_CUSTOM_TYPE_*
+ *     constants.
  *
- *      The returned value may be either an unsigned long long or a boolean.
+ *     The returned value may be either an unsigned long long or a boolean.
  *
  *     WARNING:
  *      The stats reported in this group are runtime-collected and