[libvirt] [PATCH v2] virsh: Add more human-friendly output of domblkstat command

[Peter Krempa]

Users of virsh complain that output of the domblkstat command
is not intuitive enough. This patch adds explanation of fields
returned by this command to the help section for domblkstat and
the man page of virsh. Also a switch --human is added for
domblkstat that prints the fields with more descriptive texts.

https://bugzilla.redhat.com/show_bug.cgi?id=731656

Changes to v1:
-Rebased to current head
---
 tools/virsh.c   |   52 +++++++++++++++++++++++++++++++++++++++++-----------
 tools/virsh.pod |   11 ++++++++++-
 2 files changed, 51 insertions(+), 12 deletions(-)

diff --git a/tools/virsh.c b/tools/virsh.c
index c7240e5..09337cb 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -1054,13 +1054,21 @@ cleanup:
  */
 static const vshCmdInfo info_domblkstat[] = {
     {"help", N_("get device block stats for a domain")},
-    {"desc", N_("Get device block stats for a running domain.")},
+    {"desc", N_("Get device block stats for a running domain.\n\n"
+                "    Explanation of fields:\n"
+                "      rd_req   - count of read requests\n"
+                "      rd_bytes - count of read bytes\n"
+                "      wr_req   - count of write requests\n"
+                "      wr_bytes - count of written bytes\n"
+                "      errs     - error count")},
     {NULL,NULL}
 };

 static const vshCmdOptDef opts_domblkstat[] = {
     {"domain", VSH_OT_DATA, VSH_OFLAG_REQ, N_("domain name, id or uuid")},
     {"device", VSH_OT_DATA, VSH_OFLAG_REQ, N_("block device")},
+    {"human",  VSH_OT_BOOL, 0, N_("print a more human readable output")},
+
     {NULL, 0, 0, NULL}
 };

@@ -1070,6 +1078,7 @@ cmdDomblkstat (vshControl *ctl, const vshCmd *cmd)
     virDomainPtr dom;
     const char *name = NULL, *device = NULL;
     struct _virDomainBlockStats stats;
+    int humanReadable = vshCommandOptBool(cmd, "human");

     if (!vshConnectionUsability (ctl, ctl->conn))
         return false;
@@ -1088,20 +1097,41 @@ cmdDomblkstat (vshControl *ctl, const vshCmd *cmd)
         return false;
     }

-    if (stats.rd_req >= 0)
-        vshPrint (ctl, "%s rd_req %lld\n", device, stats.rd_req);
+    if (humanReadable) {
+        /* human friendly output */
+        vshPrint(ctl, N_("Device: %s\n"), device);
+
+        if (stats.rd_req >= 0)
+            vshPrint (ctl, N_("read request count:      %lld\n"),  stats.rd_req);
+
+        if (stats.rd_bytes >= 0)
+            vshPrint (ctl, N_("number of read bytes:    %lld\n"), stats.rd_bytes);
+
+        if (stats.wr_req >= 0)
+            vshPrint (ctl, N_("write request count:     %lld\n"), stats.wr_req);

-    if (stats.rd_bytes >= 0)
-        vshPrint (ctl, "%s rd_bytes %lld\n", device, stats.rd_bytes);
+        if (stats.wr_bytes >= 0)
+            vshPrint (ctl, N_("number of written bytes: %lld\n"), stats.wr_bytes);

-    if (stats.wr_req >= 0)
-        vshPrint (ctl, "%s wr_req %lld\n", device, stats.wr_req);
+        if (stats.errs >= 0)
+            vshPrint (ctl, N_("error count:             %lld\n"), stats.errs);
+    } else {
+        /* script friendly output */
+        if (stats.rd_req >= 0)
+            vshPrint (ctl, "%s rd_req %lld\n", device, stats.rd_req);
+
+        if (stats.rd_bytes >= 0)
+            vshPrint (ctl, "%s rd_bytes %lld\n", device, stats.rd_bytes);

-    if (stats.wr_bytes >= 0)
-        vshPrint (ctl, "%s wr_bytes %lld\n", device, stats.wr_bytes);
+        if (stats.wr_req >= 0)
+            vshPrint (ctl, "%s wr_req %lld\n", device, stats.wr_req);

-    if (stats.errs >= 0)
-        vshPrint (ctl, "%s errs %lld\n", device, stats.errs);
+        if (stats.wr_bytes >= 0)
+            vshPrint (ctl, "%s wr_bytes %lld\n", device, stats.wr_bytes);
+
+        if (stats.errs >= 0)
+            vshPrint (ctl, "%s errs %lld\n", device, stats.errs);
+    }

     virDomainFree(dom);
     return true;
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 30c0721..c333b2a 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -501,10 +501,19 @@ be lost once the guest stops running, but the snapshot contents still
 exist, and a new domain with the same name and UUID can restore the
 snapshot metadata with B<snapshot-create>.

-=item B<domblkstat> I<domain> I<block-device>
+=item B<domblkstat> I<domain> I<block-device> [I<--human>]

 Get device block stats for a running domain.

+Use I<--human> for a more human readable output.
+
+B<Explanation of fields:>
+  rd_req   - count of read requests
+  rd_bytes - count of read bytes
+  wr_req   - count of write requests
+  wr_bytes - count of written bytes
+  errs     - error count
+
 =item B<domifstat> I<domain> I<interface-device>

 Get network interface stats for a running domain.
-- 
1.7.3.4