Man page: Add an explanation of columns (RHBZ#834208).

[virt-top.git] / virt-top / virt-top.pod

diff --git a/virt-top/virt-top.pod b/virt-top/virt-top.pod
index 3a955ac..56b61a1 100755 (executable)
--- a/virt-top/virt-top.pod
+++ b/virt-top/virt-top.pod
@@ -43,16 +43,21 @@ Batch mode.  In this mode keypresses are ignored.
 
 =item B<-c uri> or B<--connect uri>
 
 
 =item B<-c uri> or B<--connect uri>
 

-Connect to URI given.  The default is to connect to the Xen
-hypervisor.
+Connect to the libvirt URI given.

 
 To connect to QEMU/KVM you would normally do I<-c qemu:///system>
 
 
 To connect to QEMU/KVM you would normally do I<-c qemu:///system>
 

+To connect to Xen on the same host, do I<-c xen:///>
+

 To connect to libvirtd on a remote machine you would normally do
 To connect to libvirtd on a remote machine you would normally do

-I<-c xen://host/>
+I<-c qemu://host/system>
+
+If this option is not given then virt-top connects by default
+to whatever is the default hypervisor for libvirt, although
+this can be overridden by setting environment variables.

 
 

-Full details on connection URIs is available at
-L<http://libvirt.org/uri.html>
+See the libvirt documentation at L<http://libvirt.org/uri.html>
+for further information.

 
 =item B<-d delay>
 
 
 =item B<-d delay>
 


@@ -122,6 +127,10 @@ I<output.csv.00>, I<output.csv.01> etc.
 
 Disable domain CPU stats in CSV output.
 
 
 Disable domain CPU stats in CSV output.
 

+=item B<--no-csv-mem>
+
+Disable domain memory stats in CSV output.
+

 =item B<--no-csv-block>
 
 Disable domain block device stats in CSV output.
 =item B<--no-csv-block>
 
 Disable domain block device stats in CSV output.


@@ -346,6 +355,10 @@ Enables CSV output to the named file.
 
 Enable or disable domain CPU stats in CSV output.
 
 
 Enable or disable domain CPU stats in CSV output.
 

+=item B<csv-mem> I<true|false>
+
+Enable or disable domain memory stats in CSV output.
+

 =item B<csv-block> I<true|false>
 
 Enable or disable domain block device stats in CSV output.
 =item B<csv-block> I<true|false>
 
 Enable or disable domain block device stats in CSV output.


@@ -390,6 +403,113 @@ Note that in the current implementation, options specified in
 the init file override options specified on the command line.
 This is a bug and this behaviour may change in the future.
 
 the init file override options specified on the command line.
 This is a bug and this behaviour may change in the future.
 

+=head1 COLUMN HEADINGS
+
+=over 4
+
+=item B<%CPU>
+
+Percentage of CPU used.  As with L<top(1)>, 100% means that
+all physical CPUs are being fully used.
+
+=item B<DEVICE>
+
+The block device name.
+
+=item B<DOMAIN>
+
+=item B<NAME>
+
+The name of the libvirt domain.
+
+=item B<ID>
+
+The libvirt domain ID.
+
+=item B<INTERFACE>
+
+The network interface name.
+
+=item B<%MEM>
+
+The percentage of host memory assigned to the guest.
+
+=item B<PHYCPU>
+
+The physical CPU.
+
+=item B<RDBY>
+
+Disk bytes read since last displayed.
+
+=item B<RDRQ>
+
+Disk read requests since last displayed.
+
+=item B<RXBY>
+
+Network bytes received since last displayed.
+
+=item B<RXPK>
+
+Network packets received since last displayed.
+
+=item B<S>
+
+The state of the domain, one of:
+
+=over 4
+
+=item B<?>
+
+Unknown.
+
+=item B<R>
+
+Running.
+
+=item B<S>
+
+Blocked.
+
+=item B<P>
+
+Paused.
+
+=item B<D>
+
+=item B<O>
+
+Shutdown.
+
+=item B<X>
+
+Crashed.
+
+=back
+
+=item B<TIME>
+
+Total CPU time used.
+
+=item B<TXBY>
+
+Network bytes transmitted since last displayed.
+
+=item B<TXPK>
+
+Network packets transmitted since last displayed.
+
+=item B<WRBY>
+
+Disk bytes written since last displayed.
+
+=item B<WRRQ>
+
+Disk write requests since last displayed.
+
+=back
+

 =head1 NOTES
 
 =head2 Block I/O statistics
 =head1 NOTES
 
 =head2 Block I/O statistics


@@ -411,6 +531,20 @@ will probably see a steady "background noise" of RX packets even when
 the network interface is idle or down.  These are caused by STP
 packets generated by the bridge.
 
 the network interface is idle or down.  These are caused by STP
 packets generated by the bridge.
 

+=head2 DEBUGGING LIBVIRT ISSUES
+
+virt-top tries to turn libvirt errors into informative messages.
+However if libvirt initialization fails then this is not possible.
+Instead you will get an obscure error like:
+
+ libvir: error : Unknown failure
+ Fatal error: exception Libvirt.Virterror(...)
+
+To see the cause of libvirt errors in more detail, enable libvirt
+debugging by setting this environment variable:
+
+ export LIBVIRT_DEBUG=1
+

 =head1 SEE ALSO
 
 L<top(1)>,
 =head1 SEE ALSO
 
 L<top(1)>,


@@ -426,7 +560,7 @@ Richard W.M. Jones <rjones @ redhat . com>
 
 =head1 COPYRIGHT
 
 
 =head1 COPYRIGHT
 

-(C) Copyright 2007-2011 Red Hat Inc., Richard W.M. Jones
+(C) Copyright 2007-2012 Red Hat Inc., Richard W.M. Jones

 http://libvirt.org/
 
 This program is free software; you can redistribute it and/or modify
 http://libvirt.org/
 
 This program is free software; you can redistribute it and/or modify