+++ /dev/null
-=head1 NAME
-
-virt-top - 'top'-like utility for virtualization stats
-
-=head1 SUMMARY
-
-virt-top [-options]
-
-=head1 DESCRIPTION
-
-virt-top is a L<top(1)>-like utility for showing stats of virtualized
-domains. Many keys and command line options are the same as for
-ordinary I<top>.
-
-It uses libvirt so it is capable of showing stats across a variety of
-different virtualization systems.
-
-=head1 OPTIONS
-
-=over 4
-
-=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.
-
-=item B<-2>
-
-Display network interfaces by default (instead of domains).
-When virt-top is running, use the I<2> key to toggle
-between network interfaces and domains display.
-
-=item B<-3>
-
-Display block devices (virtual disks) by default (instead of domains).
-When virt-top is running, use the I<3> key to toggle
-between block devices and domains display.
-
-=item B<-b>
-
-Batch mode. In this mode keypresses are ignored.
-
-=item B<-c uri> or B<--connect uri>
-
-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 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.
-
-See the libvirt documentation at L<http://libvirt.org/uri.html>
-for further information.
-
-=item B<-d delay>
-
-Set the delay between screen updates in seconds.
-The default is 3.0 seconds. You can change this
-while virt-top is running by pressing either I<s> or I<d> key.
-
-=item B<-n iterations>
-
-Set the number of iterations to run. The default
-is to run continuously.
-
-=item B<-o sort>
-
-Set the sort order to one of:
-B<cpu> (sort by %CPU 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),
-B<netrx> (sort by network received bytes),
-B<nettx> (sort by network transmitted bytes),
-B<blockrdrq> (sort by block device [disk] read requests),
-B<blockwrrq> (sort by block device [disk] write requests).
-
-While virt-top is running you can change the sort
-order using keys I<P> (cpu), I<M> (memory),
-I<T> (total time), I<N> (domain ID),
-I<F> (interactively select the sort field).
-
-=item B<-s>
-
-Secure mode. Currently this does nothing.
-
-=item B<--hist-cpu secs>
-
-Set the time in seconds between updates of the historical
-%CPU at the top right of the display.
-
-=item B<--csv file.csv>
-
-Write the statistics to file I<file.csv>. First a header is written
-showing the statistics being recorded in each column, then one line is
-written for each screen update. The CSV file can be loaded directly
-by most spreadsheet programs.
-
-Currently the statistics which this records vary between releases of
-virt-top (but the column headers will stay the same, so you can use
-those to process the CSV file).
-
-Not every version of virt-top supports CSV output - it depends how the
-program was compiled (see I<README> file in the source distribution
-for details).
-
-To save space you can compress your CSV files (if your shell supports
-this feature, eg. I<bash>):
-
- virt-top --csv >(gzip -9 > output.csv.gz)
-
-You can use a similar trick to split the CSV file up. In this example
-the CSV file is split every 1000 lines into files called
-I<output.csv.00>, I<output.csv.01> etc.
-
- virt-top --csv >(split -d -l 1000 - output.csv.)
-
-=item B<--no-csv-cpu>
-
-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-net>
-
-Disable domain network interface stats in CSV output.
-
-=item B<--debug filename>
-
-Send debug and error messages to I<filename>.
-To send error messages to syslog you can do:
-
- virt-top --debug >(logger -t virt-top)
-
-See also REPORTING BUGS below.
-
-=item B<--init-file filename>
-
-Read I<filename> as the init file instead of the default which is
-I<$HOME/.virt-toprc>. See also INIT FILE below.
-
-=item B<--no-init-file>
-
-Do not read any init file.
-
-=item B<--script>
-
-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.
-
-The time may be given in one of the following formats:
-
-=over 4
-
-=item I<YYYY-MM-DD HH:MM:SS>
-
-End time is the date and time given.
-
-=item I<HH:MM:SS>
-
-End time is the time given, today.
-
-=item I<+HH:MM:SS>
-
-End time is HH hours, MM minutes, SS seconds in the future (counted
-from the moment that program starts).
-
-=item I<+secs>
-
-End time is I<secs> seconds in the future.
-
-=back
-
-For example to run the program for 3 minutes you could do:
-
- virt-top --end-time +00:03:00
-
-or:
-
- virt-top --end-time +180
-
-Not every version of virt-top supports this option - it depends how the
-program was compiled (see I<README> file in the source distribution
-for details).
-
-=item B<--help>
-
-Display usage summary.
-
-=item B<--version>
-
-Display version number and exit.
-
-=back
-
-=head1 KEYS
-
-Note that keys are case sensitive. For example use upper-case I<P>
-(shift P) to sort by %CPU. I<^> before a key means a Ctrl key, so
-I<^L> is Ctrl L.
-
-=over 4
-
-=item I<space> or I<^L>
-
-Updates the display.
-
-=item I<q>
-
-Quits the program.
-
-=item I<h>
-
-Displays help.
-
-=item I<s> or I<d>
-
-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<1> (number 1)
-
-Toggle into showing physical CPUs. If pressed
-again toggles back to showing domains (the normal
-display).
-
-=item I<2>
-
-Toggle into showing network interfaces. If pressed
-again toggles back to showing domains.
-
-=item I<3>
-
-Toggle into showing block devices (virtual disks). If pressed again
-toggles back to showing domains.
-
-=item I<P>
-
-Sort by %CPU.
-
-=item I<M>
-
-Sort by total memory. Note that this shows the total memory
-allocated to the guest, not the memory being used.
-
-=item I<T>
-
-Sort by total time.
-
-=item I<N>
-
-Sort by domain ID.
-
-=item I<F>
-
-Select the sort field interactively (there are other
-sort fields you can choose using this key).
-
-=item I<W>
-
-This creates or overwrites the init file with the current settings.
-
-This key is disabled if I<--no-init-file> was specified on the
-command line or if I<overwrite-init-file false> is given in
-the init file.
-
-=back
-
-=head1 INIT FILE
-
-When virt-top starts up, it reads initial settings from the
-file I<.virt-toprc> in the user's home directory.
-
-The name of this file may be overridden using the I<--init-file
-filename> command line option or may be disabled entirely using
-I<--no-init-file>.
-
-The init file has a simple format. Blank lines and comments
-beginning with I<#> are ignored. Everything else is a set of
-I<key value> pairs, described below.
-
-=over 4
-
-=item B<display> I<task|pcpu|block|net>
-
-Sets the major display mode to one of I<task> (tasks, the
-default), I<pcpu> (physical CPUs), I<block> (block devices),
-or I<net> (network interfaces).
-
-=item B<delay> I<secs>
-
-Sets the delay between display updates in seconds.
-
-=item B<hist-cpu> I<secs>
-
-Sets the historical CPU delay in seconds.
-
-=item B<iterations> I<n>
-
-Sets the number of iterations to run before we exit. Setting
-this to I<-1> means to run continuously.
-
-=item B<sort> I<cpu|mem|time|id|name|...>
-
-Sets the sort order. The option names are the same as for
-the command line I<-o> option.
-
-=item B<connect> I<uri>
-
-Sets the default connection URI.
-
-=item B<debug> I<filename>
-
-Sets the default filename to use for debug and error messages.
-
-=item B<csv> I<filename>
-
-Enables CSV output to the named file.
-
-=item B<csv-cpu> I<true|false>
-
-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-net> I<true|false>
-
-Enable or disable domain network interface stats in CSV output.
-
-=item B<batch> I<true|false>
-
-Sets batch mode.
-
-=item B<secure> I<true|false>
-
-Sets secure mode.
-
-=item B<script> I<true|false>
-
-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
-time formats supported.
-
-=item B<overwrite-init-file> I<false>
-
-If set to I<false> then the I<W> key will not overwrite the
-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<http://www.libvirt.org/ocaml/>,
-L<http://www.libvirt.org/>,
-L<http://people.redhat.com/~rjones/>,
-L<http://caml.inria.fr/>
-
-=head1 AUTHORS
-
-Richard W.M. Jones <rjones @ redhat . com>
-
-=head1 COPYRIGHT
-
-(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
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-
-=head1 REPORTING BUGS
-
-Bugs can be viewed on the Red Hat Bugzilla page:
-L<https://bugzilla.redhat.com/>.
-
-If you find a bug in virt-top, please follow these steps to report it:
-
-=over 4
-
-=item 1. Check for existing bug reports
-
-Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
-Someone may already have reported the same bug, and they may even
-have fixed it.
-
-=item 2. Capture debug and error messages
-
-Run
-
- virt-top --debug virt-top.log
-
-and keep I<virt-top.log>. It contains error messages which you
-should submit with your bug report.
-
-=item 3. Get version of virt-top and version of libvirt.
-
-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.
-
-Go to L<https://bugzilla.redhat.com/> and enter a new bug.
-Please describe the problem in as much detail as possible.
-
-Remember to include the version numbers (step 3) and the debug
-messages file (step 2).
-
-=item 5. Assign the bug to rjones @ redhat.com
-
-Assign or reassign the bug to B<rjones @ redhat.com> (without the
-spaces). You can also send me an email with the bug number if you
-want a faster response.
-
-=back
git.annexia.org / virt-top.git / blobdiff