Version 1.0.8.

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

diff --git a/virt-top/virt-top.pod b/virt-top/virt-top.pod
index d479b63..4d81608 100755 (executable)
--- a/virt-top/virt-top.pod
+++ b/virt-top/virt-top.pod
@@ -22,6 +22,12 @@ different virtualization systems.
 =item B<-1>
 
 Display physical CPUs by default (instead of domains).
+
+Under each domain column, two numbers are shown.  The first is
+the percentage of the physical CPU used by the domain and the
+hypervisor together.  The second is the percentage used by just
+the domain.
+
 When virt-top is running, use the I<1> key to toggle
 between physical CPUs and domains display.
 
@@ -43,16 +49,21 @@ Batch mode.  In this mode keypresses are ignored.
 
 =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 Xen on the same host, do I<-c xen:///>
+
 To connect to libvirtd on a remote machine you would normally do
-I<-c xen://host/>
+I<-c qemu://host/system>
 
-Full details on connection URIs is available at
-L<http://libvirt.org/uri.html>
+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.
+
+See the libvirt documentation at L<http://libvirt.org/uri.html>
+for further information.
 
 =item B<-d delay>
 
@@ -398,6 +409,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.
 
+=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
@@ -419,6 +537,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.
 
+=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)>,
@@ -434,7 +566,7 @@ Richard W.M. Jones <rjones @ redhat . com>
 
 =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