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 4d7df4e..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).
 =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.
 
 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>
 
 
 =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>

 
 

-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>
 
 
 =item B<-d delay>
 


@@ -122,6 +133,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.


@@ -153,6 +168,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.
 
 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.
 =item B<--end-time time>
 
 The program will exit at the I<time> given.


@@ -226,6 +250,10 @@ Displays help.
 
 Change the delay between screen updates.
 
 
 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.
 =item I<0> (number 0)
 
 Show the normal list of domains display.


@@ -333,6 +361,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.


@@ -353,6 +385,14 @@ Sets secure mode.
 
 Sets script 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
 =item B<end-time> I<time>
 
 Set the time at which the program exits.  See above for the


@@ -369,8 +409,121 @@ 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
 
 =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
 =head2 NETWORK RX BYTES AND PACKETS
 
 Libvirt/virt-top has no way to know that a packet transmitted to a


@@ -384,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.
 
 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)>,


@@ -399,7 +566,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