X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=virt-top%2Fvirt-top.pod;h=56b61a11099bf225cccaeefc55dd7eaef4b2d83c;hb=3d870f4841bb81800baeccaa531667b23e15d9d1;hp=6ad3ff434b94837cb26e0eb0a3ba383f9253acdd;hpb=1998014dafda52019e5151dc6c4c75b3b5dad7aa;p=virt-top.git

diff --git a/virt-top/virt-top.pod b/virt-top/virt-top.pod
old mode 100644
new mode 100755
index 6ad3ff4..56b61a1
--- 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>
 
-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>
+
+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>
 
@@ -69,7 +74,7 @@ is to run continuously.
 
 Set the sort order to one of:
 B<cpu> (sort by %CPU used),
-B<mem> (sort by memory used),
+B<mem> (sort by total memory),
 B<time> (sort by total time),
 B<id> (sort by domain ID),
 B<name> (sort by domain name),
@@ -122,6 +127,10 @@ I<output.csv.00>, I<output.csv.01> etc.
 
 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.
@@ -153,6 +162,15 @@ Do not read any init file.
 Script mode.  There will be no user interface.  This is most useful
 when used together with the I<--csv> and I<-n> options.
 
+=item B<--stream>
+
+Stream mode.  All output is sent to stdout.  This can be used from
+shell scripts etc.  There is no user interface.
+
+=item B<--block-in-bytes>
+
+Show I/O statistics in Bytes. Default is shown in the number of Requests.
+
 =item B<--end-time time>
 
 The program will exit at the I<time> given.
@@ -196,6 +214,10 @@ for details).
 
 Display usage summary.
 
+=item B<--version>
+
+Display version number and exit.
+
 =back
 
 =head1 KEYS
@@ -222,6 +244,10 @@ Displays help.
 
 Change the delay between screen updates.
 
+=item I<B>
+
+Toggle Block I/O statistics so they are shown in either bytes or requests.
+
 =item I<0> (number 0)
 
 Show the normal list of domains display.
@@ -248,7 +274,8 @@ Sort by %CPU.
 
 =item I<M>
 
-Sort by memory.
+Sort by total memory.  Note that this shows the total memory
+allocated to the guest, not the memory being used.
 
 =item I<T>
 
@@ -328,6 +355,10 @@ Enables CSV output to the named file.
 
 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.
@@ -348,6 +379,14 @@ Sets secure mode.
 
 Sets script mode.
 
+=item B<stream> I<true|false>
+
+Sets stream mode.
+
+=item B<block-in-bytes> I<true|false>
+
+Show block device statistics in bytes.
+
 =item B<end-time> I<time>
 
 Set the time at which the program exits.  See above for the
@@ -360,19 +399,159 @@ init file.
 
 =back
 
-
 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
+
+This I/O value is the amount of I/O since the previous iteration
+of virt-top. To calculate speed of I/O, you should divide
+the number by delay secs.
+
+=head2 NETWORK RX BYTES AND PACKETS
+
+Libvirt/virt-top has no way to know that a packet transmitted to a
+guest was received (eg. if the guest is not listening).  In the
+network RX stats, virt-top reports the packets transmitted to the
+guest, on the basis that the guest might receive them.
+
+In particular this includes broadcast packets.  Because of the way
+that Linux bridges work, if the guest is connected to a bridge, it
+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)>,
 L<virsh(1)>,
-L<xm(1)>,
-L<xentop(1)>,
+L<http://www.libvirt.org/ocaml/>,
 L<http://www.libvirt.org/>,
-L<http://et.redhat.com/~rjones/>,
+L<http://people.redhat.com/~rjones/>,
 L<http://caml.inria.fr/>
 
 =head1 AUTHORS
@@ -381,7 +560,7 @@ Richard W.M. Jones <rjones @ redhat . com>
 
 =head1 COPYRIGHT
 
-(C) Copyright 2007 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
@@ -424,9 +603,12 @@ should submit with your bug report.
 
 =item 3. Get version of virt-top and version of libvirt.
 
-In virt-top, press the I<h> (help) key, and write down the version of
-virt-top and the version of libvirt.  They are shown in the first
-line.
+Use:
+
+ virt-top --version
+
+If you can get the precise version of libvirt you are using
+then that too is helpful.
 
 =item 4. Submit a bug report.
 
@@ -443,5 +625,3 @@ spaces).  You can also send me an email with the bug number if you
 want a faster response.
 
 =back
-
-=end