Introduce virDomainGetJobStats API

This is an extensible version of virDomainGetJobInfo.

include/libvirt/libvirt.h.in

@@ -3945,8 +3945,213 @@ struct _virDomainJobInfo {
 
 int virDomainGetJobInfo(virDomainPtr dom,
                         virDomainJobInfoPtr info);
+int virDomainGetJobStats(virDomainPtr domain,
+                         int *type,
+                         virTypedParameterPtr *params,
+                         int *nparams,
+                         unsigned int flags);
 int virDomainAbortJob(virDomainPtr dom);
 
+/**
+ * VIR_DOMAIN_JOB_TIME_ELAPSED:
+ *
+ * virDomainGetJobStats field: time (ms) since the beginning of the
+ * job, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to timeElapsed field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_TIME_ELAPSED             "time_elapsed"
+
+/**
+ * VIR_DOMAIN_JOB_TIME_REMAINING:
+ *
+ * virDomainGetJobStats field: remaining time (ms) for VIR_DOMAIN_JOB_BOUNDED
+ * jobs, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to timeRemaining field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_TIME_REMAINING           "time_remaining"
+
+/**
+ * VIR_DOMAIN_JOB_DOWNTIME:
+ *
+ * virDomainGetJobStats field: downtime (ms) that is expected to happen
+ * during migration, as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_DOWNTIME                 "downtime"
+
+/**
+ * VIR_DOMAIN_JOB_DATA_TOTAL:
+ *
+ * virDomainGetJobStats field: total number of bytes supposed to be
+ * transferred, as VIR_TYPED_PARAM_ULLONG. For VIR_DOMAIN_JOB_UNBOUNDED
+ * jobs, this may be less than the sum of VIR_DOMAIN_JOB_DATA_PROCESSED and
+ * VIR_DOMAIN_JOB_DATA_REMAINING in the event that the hypervisor has to
+ * repeat some data, e.g., due to dirtied pages during migration. For
+ * VIR_DOMAIN_JOB_BOUNDED jobs, VIR_DOMAIN_JOB_DATA_TOTAL shall always equal
+ * VIR_DOMAIN_JOB_DATA_PROCESSED + VIR_DOMAIN_JOB_DATA_REMAINING.
+ *
+ * This field corresponds to dataTotal field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_DATA_TOTAL               "data_total"
+
+/**
+ * VIR_DOMAIN_JOB_DATA_PROCESSED:
+ *
+ * virDomainGetJobStats field: number of bytes transferred from the
+ * beginning of the job, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to dataProcessed field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_DATA_PROCESSED           "data_processed"
+
+/**
+ * VIR_DOMAIN_JOB_DATA_REMAINING:
+ *
+ * virDomainGetJobStats field: number of bytes that still need to be
+ * transferred, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to dataRemaining field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_DATA_REMAINING           "data_remaining"
+
+/**
+ * VIR_DOMAIN_JOB_MEMORY_TOTAL:
+ *
+ * virDomainGetJobStats field: as VIR_DOMAIN_JOB_DATA_TOTAL but only
+ * tracking guest memory progress, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to memTotal field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_MEMORY_TOTAL             "memory_total"
+
+/**
+ * VIR_DOMAIN_JOB_MEMORY_PROCESSED:
+ *
+ * virDomainGetJobStats field: as VIR_DOMAIN_JOB_DATA_PROCESSED but only
+ * tracking guest memory progress, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to memProcessed field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_MEMORY_PROCESSED         "memory_processed"
+
+/**
+ * VIR_DOMAIN_JOB_MEMORY_REMAINING:
+ *
+ * virDomainGetJobStats field: as VIR_DOMAIN_JOB_DATA_REMAINING but only
+ * tracking guest memory progress, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to memRemaining field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_MEMORY_REMAINING         "memory_remaining"
+
+/**
+ * VIR_DOMAIN_JOB_MEMORY_CONSTANT:
+ *
+ * virDomainGetJobStats field: number of pages filled with a constant
+ * byte (all bytes in a single page are identical) transferred since the
+ * beginning of the migration job, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * The most common example of such pages are zero pages, i.e., pages filled
+ * with zero bytes.
+ */
+#define VIR_DOMAIN_JOB_MEMORY_CONSTANT          "memory_constant"
+
+/**
+ * VIR_DOMAIN_JOB_MEMORY_NORMAL:
+ *
+ * virDomainGetJobStats field: number of pages that were transferred without
+ * any kind of compression (i.e., pages which were not filled with a constant
+ * byte and which could not be compressed) transferred since the beginning
+ * of the migration job, as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_MEMORY_NORMAL            "memory_normal"
+
+/**
+ * VIR_DOMAIN_JOB_MEMORY_NORMAL_BYTES:
+ *
+ * virDomainGetJobStats field: number of bytes transferred as normal pages,
+ * as VIR_TYPED_PARAM_ULLONG.
+ *
+ * See VIR_DOMAIN_JOB_MEMORY_NORMAL for more details.
+ */
+#define VIR_DOMAIN_JOB_MEMORY_NORMAL_BYTES      "memory_normal_bytes"
+
+/**
+ * VIR_DOMAIN_JOB_DISK_TOTAL:
+ *
+ * virDomainGetJobStats field: as VIR_DOMAIN_JOB_DATA_TOTAL but only
+ * tracking guest disk progress, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to fileTotal field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_DISK_TOTAL               "disk_total"
+
+/**
+ * VIR_DOMAIN_JOB_DISK_PROCESSED:
+ *
+ * virDomainGetJobStats field: as VIR_DOMAIN_JOB_DATA_PROCESSED but only
+ * tracking guest disk progress, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to fileProcessed field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_DISK_PROCESSED           "disk_processed"
+
+/**
+ * VIR_DOMAIN_JOB_DISK_REMAINING:
+ *
+ * virDomainGetJobStats field: as VIR_DOMAIN_JOB_DATA_REMAINING but only
+ * tracking guest disk progress, as VIR_TYPED_PARAM_ULLONG.
+ *
+ * This field corresponds to fileRemaining field in virDomainJobInfo.
+ */
+#define VIR_DOMAIN_JOB_DISK_REMAINING           "disk_remaining"
+
+/**
+ * VIR_DOMAIN_JOB_COMPRESSION_CACHE:
+ *
+ * virDomainGetJobStats field: size of the cache (in bytes) used for
+ * compressing repeatedly transferred memory pages during live migration,
+ * as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_COMPRESSION_CACHE        "compression_cache"
+
+/**
+ * VIR_DOMAIN_JOB_COMPRESSION_BYTES:
+ *
+ * virDomainGetJobStats field: number of compressed bytes transferred
+ * since the beginning of migration, as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_COMPRESSION_BYTES        "compression_bytes"
+
+/**
+ * VIR_DOMAIN_JOB_COMPRESSION_PAGES:
+ *
+ * virDomainGetJobStats field: number of compressed pages transferred
+ * since the beginning of migration, as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_COMPRESSION_PAGES        "compression_pages"
+
+/**
+ * VIR_DOMAIN_JOB_COMPRESSION_CACHE_MISSES:
+ *
+ * virDomainGetJobStats field: number of repeatedly changing pages that
+ * were not found in compression cache and thus could not be compressed,
+ * as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_COMPRESSION_CACHE_MISSES "compression_cache_misses"
+
+/**
+ * VIR_DOMAIN_JOB_COMPRESSION_OVERFLOW:
+ *
+ * virDomainGetJobStats field: number of repeatedly changing pages that
+ * were found in compression cache but were sent uncompressed because
+ * the result of compression was larger than the original page as a whole,
+ * as VIR_TYPED_PARAM_ULLONG.
+ */
+#define VIR_DOMAIN_JOB_COMPRESSION_OVERFLOW     "compression_overflow"
+
+
 /**
  * virDomainSnapshot:
  *

python/generator.py

@@ -389,6 +389,7 @@ skip_impl = (
     'virDomainGetControlInfo',
     'virDomainGetBlockInfo',
     'virDomainGetJobInfo',
+    'virDomainGetJobStats',
     'virNodeGetInfo',
     'virDomainGetUUID',
     'virDomainGetUUIDString',

src/driver.h

@@ -590,6 +590,12 @@ typedef char *
 typedef int
     (*virDrvDomainGetJobInfo)(virDomainPtr domain,
                               virDomainJobInfoPtr info);
+typedef int
+    (*virDrvDomainGetJobStats)(virDomainPtr domain,
+                               int *type,
+                               virTypedParameterPtr *params,
+                               int *nparams,
+                               unsigned int flags);
 
 typedef int
     (*virDrvDomainAbortJob)(virDomainPtr domain);
@@ -1060,6 +1066,7 @@ struct _virDriver {
     virDrvCompareCPU                    cpuCompare;
     virDrvBaselineCPU                   cpuBaseline;
     virDrvDomainGetJobInfo              domainGetJobInfo;
+    virDrvDomainGetJobStats             domainGetJobStats;
     virDrvDomainAbortJob                domainAbortJob;
     virDrvDomainMigrateSetMaxDowntime   domainMigrateSetMaxDowntime;
     virDrvDomainMigrateGetMaxSpeed      domainMigrateGetMaxSpeed;

src/libvirt.c

@@ -17398,6 +17398,66 @@ error:
 }
 
 
+/**
+ * virDomainGetJobStats:
+ * @domain: a domain object
+ * @type: where to store the job type (one of virDomainJobType)
+ * @params: where to store job statistics
+ * @nparams: number of items in @params
+ * @flags: extra flags; not used yet, so callers should always pass 0
+ *
+ * Extract information about progress of a background job on a domain.
+ * Will return an error if the domain is not active. The function returns
+ * a superset of progress information provided by virDomainGetJobInfo.
+ * Possible fields returned in @params are defined by VIR_DOMAIN_JOB_*
+ * macros and new fields will likely be introduced in the future so callers
+ * may receive fields that they do not understand in case they talk to a
+ * newer server.
+ *
+ * Returns 0 in case of success and -1 in case of failure.
+ */
+int
+virDomainGetJobStats(virDomainPtr domain,
+                     int *type,
+                     virTypedParameterPtr *params,
+                     int *nparams,
+                     unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(domain, "type=%p, params=%p, nparams=%p, flags=%x",
+                     type, params, nparams, flags);
+
+    virResetLastError();
+
+    if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
+        virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
+        virDispatchError(NULL);
+        return -1;
+    }
+    virCheckNonNullArgGoto(type, error);
+    virCheckNonNullArgGoto(params, error);
+    virCheckNonNullArgGoto(nparams, error);
+
+    conn = domain->conn;
+
+    if (conn->driver->domainGetJobStats) {
+        int ret;
+        ret = conn->driver->domainGetJobStats(domain, type, params,
+                                              nparams, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
+
+error:
+    virDispatchError(domain->conn);
+    return -1;
+}
+
+
 /**
  * virDomainAbortJob:
  * @domain: a domain object

src/libvirt_public.syms

@@ -605,6 +605,7 @@ LIBVIRT_1.0.2 {
 
 LIBVIRT_1.0.3 {
     global:
+        virDomainGetJobStats;
         virNodeDeviceLookupSCSIHostByWWN;
 } LIBVIRT_1.0.2;