[Qemu-devel] [PATCH 0/2] qemu-img.texi: Provide more info on some commands’ output

[Qemu-devel] [PATCH 0/2] qemu-img.texi: Provide more info on some commands’ output

[Max Reitz]

Most qemu-img subcommands that have (optional) JSON output don’t
describe the structure of their JSON output -- but having a fixed,
well-known output structure kind of is the point of having JSON output
at all.  Therefore, patch 1 in this series makes every such command note
which QAPI type their JSON output has in the qemu-img man page.  (The
exception to this is the map subcommand, which does not emit a
QAPI-typed object.  It already has a description of the structure of its
output object, though.)

That should be enough to thoroughly explain the machine-readable output.
But we can also do better for the human-readable output: qemu-img info
emits quite a bit of information, and not all of it is self-explanatory.
In patch 2, I’ve tried to provide some potentially missing explanation.


Max Reitz (2):
  qemu-img.texi: Be specific about JSON object types
  qemu-img.texi: Describe human-readable info output

 qemu-img.texi | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 3 deletions(-)

-- 
2.21.0

[Qemu-devel] [PATCH 1/2] qemu-img.texi: Be specific about JSON object types

[Max Reitz]

Just writing that --output=json outputs JSON information does not really
help; we should also make a note of what QAPI type the result object
has.  (The map subcommand does not emit a QAPI-typed object, but its
section already describes the object structure well enough.)

Signed-off-by: Max Reitz <mreitz@redhat.com>
---
 qemu-img.texi | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index 724f244ba1..39562317ee 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -230,6 +230,7 @@ overridden with a pattern byte specified by @var{pattern}.
 
 Perform a consistency check on the disk image @var{filename}. The command can
 output in the format @var{ofmt} which is either @code{human} or @code{json}.
+The JSON output is an object of QAPI type @code{ImageCheck}.
 
 If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
 during the check. @code{-r leaks} repairs only cluster leaks, whereas
@@ -406,8 +407,7 @@ The size syntax is similar to dd(1)'s size syntax.
 Give information about the disk image @var{filename}. Use it in
 particular to know the size reserved on disk which can be different
 from the displayed size. If VM snapshots are stored in the disk image,
-they are displayed too. The command can output in the format @var{ofmt}
-which is either @code{human} or @code{json}.
+they are displayed too.
 
 If a disk image has a backing file chain, information about each disk image in
 the chain can be recursively enumerated by using the option @code{--backing-chain}.
@@ -424,6 +424,10 @@ To enumerate information about each disk image in the above chain, starting from
 qemu-img info --backing-chain snap2.qcow2
 @end example
 
+The command can output in the format @var{ofmt} which is either @code{human} or
+@code{json}.  The JSON output is an object of QAPI type @code{ImageInfo}; with
+@code{--backing-chain}, it is an array of @code{ImageInfo} objects.
+
 @item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [-U] @var{filename}
 
 Dump the metadata of image @var{filename} and its backing file chain.
@@ -485,7 +489,8 @@ Calculate the file size required for a new image.  This information can be used
 to size logical volumes or SAN LUNs appropriately for the image that will be
 placed in them.  The values reported are guaranteed to be large enough to fit
 the image.  The command can output in the format @var{ofmt} which is either
-@code{human} or @code{json}.
+@code{human} or @code{json}.  The JSON output is an object of QAPI type
+@code{BlockMeasureInfo}.
 
 If the size @var{N} is given then act as if creating a new empty image file
 using @command{qemu-img create}.  If @var{filename} is given then act as if
-- 
2.21.0

[Qemu-devel] [PATCH 2/2] qemu-img.texi: Describe human-readable info output

[Max Reitz]

Ideally, it should be self-explanatory.  However, keys like "disk size"
arguably really are not self-explanatory.  In any case, there is no harm
in going into a some more detail here.

Signed-off-by: Max Reitz <mreitz@redhat.com>
---
 qemu-img.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/qemu-img.texi b/qemu-img.texi
index 39562317ee..e8bc0fd7a2 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -428,6 +428,47 @@ The command can output in the format @var{ofmt} which is either @code{human} or
 @code{json}.  The JSON output is an object of QAPI type @code{ImageInfo}; with
 @code{--backing-chain}, it is an array of @code{ImageInfo} objects.
 
+@code{--output=human} reports the following information (for every image in the
+chain):
+@table @var
+@item image
+The image file name
+
+@item file format
+The image format
+
+@item virtual size
+The size of the guest disk
+
+@item disk size
+How much space the image file occupies on the host file system (may be shown as
+0 if this information is unavailable, e.g. because there is no file system)
+
+@item cluster_size
+Cluster size of the image format, if applicable
+
+@item encrypted
+Whether the image is encrypted (only present if so)
+
+@item cleanly shut down
+This is shown as @code{no} if the image is dirty and will have to be
+auto-repaired the next time it is opened in qemu.
+
+@item backing file
+The backing file name, if present
+
+@item backing file format
+The format of the backing file, if the image enforces it
+
+@item Snapshot list
+A list of all internal snapshots
+
+@item Format specific information
+Further information whose structure depends on the image format.  This section
+is a textual representation of the respective @code{ImageInfoSpecific*} QAPI
+object (e.g. @code{ImageInfoSpecificQCow2} for qcow2 images).
+@end table
+
 @item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [-U] @var{filename}
 
 Dump the metadata of image @var{filename} and its backing file chain.
-- 
2.21.0

Re: [Qemu-devel] [PATCH 0/2] qemu-img.texi: Provide more info on some commands’ output

[Kevin Wolf]

Am 15.05.2019 um 09:59 hat Max Reitz geschrieben:
> Most qemu-img subcommands that have (optional) JSON output don’t
> describe the structure of their JSON output -- but having a fixed,
> well-known output structure kind of is the point of having JSON output
> at all.  Therefore, patch 1 in this series makes every such command note
> which QAPI type their JSON output has in the qemu-img man page.  (The
> exception to this is the map subcommand, which does not emit a
> QAPI-typed object.  It already has a description of the structure of its
> output object, though.)
> 
> That should be enough to thoroughly explain the machine-readable output.
> But we can also do better for the human-readable output: qemu-img info
> emits quite a bit of information, and not all of it is self-explanatory.
> In patch 2, I’ve tried to provide some potentially missing explanation.

Thanks, applied to the block branch.

Kevin