[libvirt] [PATCH] 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
---
 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 15b9bdd..41ba1e4 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 81d7a1e..620097d 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -419,10 +419,19 @@ the B<shutdown> command instead.  However, this does not delete any
 storage volumes used by the guest, and if the domain is persistent, it
 can be restarted later.

-=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