+++ /dev/null
-.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
-. ds C` ""
-. ds C' ""
-'br\}
-.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
-'br\}
-.\"
-.\" Escape single quotes in literal strings from groff's Unicode transform.
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.ie \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. nr % 0
-. rr F
-.\}
-.el \{\
-. de IX
-..
-.\}
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "VIRT-TOP 1"
-.TH VIRT-TOP 1 "2011-02-02" "virt-top-1.0.5" "Virtualization Support"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.if n .ad l
-.nh
-.SH "NAME"
-virt\-top \- 'top'\-like utility for virtualization stats
-.SH "SUMMARY"
-.IX Header "SUMMARY"
-virt-top [\-options]
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-virt-top is a \fItop\fR\|(1)\-like utility for showing stats of virtualized
-domains. Many keys and command line options are the same as for
-ordinary \fItop\fR.
-.PP
-It uses libvirt so it is capable of showing stats across a variety of
-different virtualization systems.
-.SH "OPTIONS"
-.IX Header "OPTIONS"
-.IP "\fB\-1\fR" 4
-.IX Item "-1"
-Display physical CPUs by default (instead of domains).
-When virt-top is running, use the \fI1\fR key to toggle
-between physical CPUs and domains display.
-.IP "\fB\-2\fR" 4
-.IX Item "-2"
-Display network interfaces by default (instead of domains).
-When virt-top is running, use the \fI2\fR key to toggle
-between network interfaces and domains display.
-.IP "\fB\-3\fR" 4
-.IX Item "-3"
-Display block devices (virtual disks) by default (instead of domains).
-When virt-top is running, use the \fI3\fR key to toggle
-between block devices and domains display.
-.IP "\fB\-b\fR" 4
-.IX Item "-b"
-Batch mode. In this mode keypresses are ignored.
-.IP "\fB\-c uri\fR or \fB\-\-connect uri\fR" 4
-.IX Item "-c uri or --connect uri"
-Connect to \s-1URI\s0 given. The default is to connect to the Xen
-hypervisor.
-.Sp
-To connect to \s-1QEMU/KVM\s0 you would normally do \fI\-c qemu:///system\fR
-.Sp
-To connect to libvirtd on a remote machine you would normally do
-\&\fI\-c xen://host/\fR
-.Sp
-Full details on connection URIs is available at
-<http://libvirt.org/uri.html>
-.IP "\fB\-d delay\fR" 4
-.IX Item "-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 \fIs\fR or \fId\fR key.
-.IP "\fB\-n iterations\fR" 4
-.IX Item "-n iterations"
-Set the number of iterations to run. The default
-is to run continuously.
-.IP "\fB\-o sort\fR" 4
-.IX Item "-o sort"
-Set the sort order to one of:
-\&\fBcpu\fR (sort by \f(CW%CPU\fR used),
-\&\fBmem\fR (sort by total memory),
-\&\fBtime\fR (sort by total time),
-\&\fBid\fR (sort by domain \s-1ID\s0),
-\&\fBname\fR (sort by domain name),
-\&\fBnetrx\fR (sort by network received bytes),
-\&\fBnettx\fR (sort by network transmitted bytes),
-\&\fBblockrdrq\fR (sort by block device [disk] read requests),
-\&\fBblockwrrq\fR (sort by block device [disk] write requests).
-.Sp
-While virt-top is running you can change the sort
-order using keys \fIP\fR (cpu), \fIM\fR (memory),
-\&\fIT\fR (total time), \fIN\fR (domain \s-1ID\s0),
-\&\fIF\fR (interactively select the sort field).
-.IP "\fB\-s\fR" 4
-.IX Item "-s"
-Secure mode. Currently this does nothing.
-.IP "\fB\-\-hist\-cpu secs\fR" 4
-.IX Item "--hist-cpu secs"
-Set the time in seconds between updates of the historical
-\&\f(CW%CPU\fR at the top right of the display.
-.IP "\fB\-\-csv file.csv\fR" 4
-.IX Item "--csv file.csv"
-Write the statistics to file \fIfile.csv\fR. First a header is written
-showing the statistics being recorded in each column, then one line is
-written for each screen update. The \s-1CSV\s0 file can be loaded directly
-by most spreadsheet programs.
-.Sp
-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 \s-1CSV\s0 file).
-.Sp
-Not every version of virt-top supports \s-1CSV\s0 output \- it depends how the
-program was compiled (see \fI\s-1README\s0\fR file in the source distribution
-for details).
-.Sp
-To save space you can compress your \s-1CSV\s0 files (if your shell supports
-this feature, eg. \fIbash\fR):
-.Sp
-.Vb 1
-\& virt\-top \-\-csv >(gzip \-9 > output.csv.gz)
-.Ve
-.Sp
-You can use a similar trick to split the \s-1CSV\s0 file up. In this example
-the \s-1CSV\s0 file is split every 1000 lines into files called
-\&\fIoutput.csv.00\fR, \fIoutput.csv.01\fR etc.
-.Sp
-.Vb 1
-\& virt\-top \-\-csv >(split \-d \-l 1000 \- output.csv.)
-.Ve
-.IP "\fB\-\-no\-csv\-cpu\fR" 4
-.IX Item "--no-csv-cpu"
-Disable domain \s-1CPU\s0 stats in \s-1CSV\s0 output.
-.IP "\fB\-\-no\-csv\-block\fR" 4
-.IX Item "--no-csv-block"
-Disable domain block device stats in \s-1CSV\s0 output.
-.IP "\fB\-\-no\-csv\-net\fR" 4
-.IX Item "--no-csv-net"
-Disable domain network interface stats in \s-1CSV\s0 output.
-.IP "\fB\-\-debug filename\fR" 4
-.IX Item "--debug filename"
-Send debug and error messages to \fIfilename\fR.
-To send error messages to syslog you can do:
-.Sp
-.Vb 1
-\& virt\-top \-\-debug >(logger \-t virt\-top)
-.Ve
-.Sp
-See also \s-1REPORTING\s0 \s-1BUGS\s0 below.
-.IP "\fB\-\-init\-file filename\fR" 4
-.IX Item "--init-file filename"
-Read \fIfilename\fR as the init file instead of the default which is
-\&\fI\f(CI$HOME\fI/.virt\-toprc\fR. See also \s-1INIT\s0 \s-1FILE\s0 below.
-.IP "\fB\-\-no\-init\-file\fR" 4
-.IX Item "--no-init-file"
-Do not read any init file.
-.IP "\fB\-\-script\fR" 4
-.IX Item "--script"
-Script mode. There will be no user interface. This is most useful
-when used together with the \fI\-\-csv\fR and \fI\-n\fR options.
-.IP "\fB\-\-stream\fR" 4
-.IX Item "--stream"
-Stream mode. All output is sent to stdout. This can be used from
-shell scripts etc. There is no user interface.
-.IP "\fB\-\-block\-in\-bytes\fR" 4
-.IX Item "--block-in-bytes"
-Show I/O statistics in Bytes. Default is shown in the number of Requests.
-.IP "\fB\-\-end\-time time\fR" 4
-.IX Item "--end-time time"
-The program will exit at the \fItime\fR given.
-.Sp
-The time may be given in one of the following formats:
-.RS 4
-.IP "\fIYYYY-MM-DD \s-1HH:MM:SS\s0\fR" 4
-.IX Item "YYYY-MM-DD HH:MM:SS"
-End time is the date and time given.
-.IP "\fI\s-1HH:MM:SS\s0\fR" 4
-.IX Item "HH:MM:SS"
-End time is the time given, today.
-.IP "\fI+HH:MM:SS\fR" 4
-.IX Item "+HH:MM:SS"
-End time is \s-1HH\s0 hours, \s-1MM\s0 minutes, \s-1SS\s0 seconds in the future (counted
-from the moment that program starts).
-.IP "\fI+secs\fR" 4
-.IX Item "+secs"
-End time is \fIsecs\fR seconds in the future.
-.RE
-.RS 4
-.Sp
-For example to run the program for 3 minutes you could do:
-.Sp
-.Vb 1
-\& virt\-top \-\-end\-time +00:03:00
-.Ve
-.Sp
-or:
-.Sp
-.Vb 1
-\& virt\-top \-\-end\-time +180
-.Ve
-.Sp
-Not every version of virt-top supports this option \- it depends how the
-program was compiled (see \fI\s-1README\s0\fR file in the source distribution
-for details).
-.RE
-.IP "\fB\-\-help\fR" 4
-.IX Item "--help"
-Display usage summary.
-.IP "\fB\-\-version\fR" 4
-.IX Item "--version"
-Display version number and exit.
-.SH "KEYS"
-.IX Header "KEYS"
-Note that keys are case sensitive. For example use upper-case \fIP\fR
-(shift P) to sort by \f(CW%CPU\fR. \fI^\fR before a key means a Ctrl key, so
-\&\fI^L\fR is Ctrl L.
-.IP "\fIspace\fR or \fI^L\fR" 4
-.IX Item "space or ^L"
-Updates the display.
-.IP "\fIq\fR" 4
-.IX Item "q"
-Quits the program.
-.IP "\fIh\fR" 4
-.IX Item "h"
-Displays help.
-.IP "\fIs\fR or \fId\fR" 4
-.IX Item "s or d"
-Change the delay between screen updates.
-.IP "\fIB\fR" 4
-.IX Item "B"
-Toggle Block I/O statistics so they are shown in either bytes or requests.
-.IP "\fI0\fR (number 0)" 4
-.IX Item "0 (number 0)"
-Show the normal list of domains display.
-.IP "\fI1\fR (number 1)" 4
-.IX Item "1 (number 1)"
-Toggle into showing physical CPUs. If pressed
-again toggles back to showing domains (the normal
-display).
-.IP "\fI2\fR" 4
-.IX Item "2"
-Toggle into showing network interfaces. If pressed
-again toggles back to showing domains.
-.IP "\fI3\fR" 4
-.IX Item "3"
-Toggle into showing block devices (virtual disks). If pressed again
-toggles back to showing domains.
-.IP "\fIP\fR" 4
-.IX Item "P"
-Sort by \f(CW%CPU\fR.
-.IP "\fIM\fR" 4
-.IX Item "M"
-Sort by total memory. Note that this shows the total memory
-allocated to the guest, not the memory being used.
-.IP "\fIT\fR" 4
-.IX Item "T"
-Sort by total time.
-.IP "\fIN\fR" 4
-.IX Item "N"
-Sort by domain \s-1ID\s0.
-.IP "\fIF\fR" 4
-.IX Item "F"
-Select the sort field interactively (there are other
-sort fields you can choose using this key).
-.IP "\fIW\fR" 4
-.IX Item "W"
-This creates or overwrites the init file with the current settings.
-.Sp
-This key is disabled if \fI\-\-no\-init\-file\fR was specified on the
-command line or if \fIoverwrite-init-file false\fR is given in
-the init file.
-.SH "INIT FILE"
-.IX Header "INIT FILE"
-When virt-top starts up, it reads initial settings from the
-file \fI.virt\-toprc\fR in the user's home directory.
-.PP
-The name of this file may be overridden using the \fI\-\-init\-file
-filename\fR command line option or may be disabled entirely using
-\&\fI\-\-no\-init\-file\fR.
-.PP
-The init file has a simple format. Blank lines and comments
-beginning with \fI#\fR are ignored. Everything else is a set of
-\&\fIkey value\fR pairs, described below.
-.IP "\fBdisplay\fR \fItask|pcpu|block|net\fR" 4
-.IX Item "display task|pcpu|block|net"
-Sets the major display mode to one of \fItask\fR (tasks, the
-default), \fIpcpu\fR (physical CPUs), \fIblock\fR (block devices),
-or \fInet\fR (network interfaces).
-.IP "\fBdelay\fR \fIsecs\fR" 4
-.IX Item "delay secs"
-Sets the delay between display updates in seconds.
-.IP "\fBhist-cpu\fR \fIsecs\fR" 4
-.IX Item "hist-cpu secs"
-Sets the historical \s-1CPU\s0 delay in seconds.
-.IP "\fBiterations\fR \fIn\fR" 4
-.IX Item "iterations n"
-Sets the number of iterations to run before we exit. Setting
-this to \fI\-1\fR means to run continuously.
-.IP "\fBsort\fR \fIcpu|mem|time|id|name|...\fR" 4
-.IX Item "sort cpu|mem|time|id|name|..."
-Sets the sort order. The option names are the same as for
-the command line \fI\-o\fR option.
-.IP "\fBconnect\fR \fIuri\fR" 4
-.IX Item "connect uri"
-Sets the default connection \s-1URI\s0.
-.IP "\fBdebug\fR \fIfilename\fR" 4
-.IX Item "debug filename"
-Sets the default filename to use for debug and error messages.
-.IP "\fBcsv\fR \fIfilename\fR" 4
-.IX Item "csv filename"
-Enables \s-1CSV\s0 output to the named file.
-.IP "\fBcsv-cpu\fR \fItrue|false\fR" 4
-.IX Item "csv-cpu true|false"
-Enable or disable domain \s-1CPU\s0 stats in \s-1CSV\s0 output.
-.IP "\fBcsv-block\fR \fItrue|false\fR" 4
-.IX Item "csv-block true|false"
-Enable or disable domain block device stats in \s-1CSV\s0 output.
-.IP "\fBcsv-net\fR \fItrue|false\fR" 4
-.IX Item "csv-net true|false"
-Enable or disable domain network interface stats in \s-1CSV\s0 output.
-.IP "\fBbatch\fR \fItrue|false\fR" 4
-.IX Item "batch true|false"
-Sets batch mode.
-.IP "\fBsecure\fR \fItrue|false\fR" 4
-.IX Item "secure true|false"
-Sets secure mode.
-.IP "\fBscript\fR \fItrue|false\fR" 4
-.IX Item "script true|false"
-Sets script mode.
-.IP "\fBstream\fR \fItrue|false\fR" 4
-.IX Item "stream true|false"
-Sets stream mode.
-.IP "\fBblock-in-bytes\fR \fItrue|false\fR" 4
-.IX Item "block-in-bytes true|false"
-Show block device statistics in bytes.
-.IP "\fBend-time\fR \fItime\fR" 4
-.IX Item "end-time time"
-Set the time at which the program exits. See above for the
-time formats supported.
-.IP "\fBoverwrite-init-file\fR \fIfalse\fR" 4
-.IX Item "overwrite-init-file false"
-If set to \fIfalse\fR then the \fIW\fR key will not overwrite the
-init file.
-.PP
-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.
-.SH "NOTES"
-.IX Header "NOTES"
-.SS "Block I/O statistics"
-.IX Subsection "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.
-.SS "\s-1NETWORK\s0 \s-1RX\s0 \s-1BYTES\s0 \s-1AND\s0 \s-1PACKETS\s0"
-.IX Subsection "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 \s-1RX\s0 stats, virt-top reports the packets transmitted to the
-guest, on the basis that the guest might receive them.
-.PP
-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 \*(L"background noise\*(R" of \s-1RX\s0 packets even when
-the network interface is idle or down. These are caused by \s-1STP\s0
-packets generated by the bridge.
-.SH "SEE ALSO"
-.IX Header "SEE ALSO"
-\&\fItop\fR\|(1),
-\&\fIvirsh\fR\|(1),
-<http://www.libvirt.org/ocaml/>,
-<http://www.libvirt.org/>,
-<http://people.redhat.com/~rjones/>,
-<http://caml.inria.fr/>
-.SH "AUTHORS"
-.IX Header "AUTHORS"
-Richard W.M. Jones <rjones @ redhat . com>
-.SH "COPYRIGHT"
-.IX Header "COPYRIGHT"
-(C) Copyright 2007\-2011 Red Hat Inc., Richard W.M. Jones
-http://libvirt.org/
-.PP
-This program is free software; you can redistribute it and/or modify
-it under the terms of the \s-1GNU\s0 General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-.PP
-This program is distributed in the hope that it will be useful,
-but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
-\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the
-\&\s-1GNU\s0 General Public License for more details.
-.PP
-You should have received a copy of the \s-1GNU\s0 General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 675 Mass Ave, Cambridge, \s-1MA\s0 02139, \s-1USA\s0.
-.SH "REPORTING BUGS"
-.IX Header "REPORTING BUGS"
-Bugs can be viewed on the Red Hat Bugzilla page:
-<https://bugzilla.redhat.com/>.
-.PP
-If you find a bug in virt-top, please follow these steps to report it:
-.IP "1. Check for existing bug reports" 4
-.IX Item "1. Check for existing bug reports"
-Go to <https://bugzilla.redhat.com/> and search for similar bugs.
-Someone may already have reported the same bug, and they may even
-have fixed it.
-.IP "2. Capture debug and error messages" 4
-.IX Item "2. Capture debug and error messages"
-Run
-.Sp
-.Vb 1
-\& virt\-top \-\-debug virt\-top.log
-.Ve
-.Sp
-and keep \fIvirt\-top.log\fR. It contains error messages which you
-should submit with your bug report.
-.IP "3. Get version of virt-top and version of libvirt." 4
-.IX Item "3. Get version of virt-top and version of libvirt."
-Use:
-.Sp
-.Vb 1
-\& virt\-top \-\-version
-.Ve
-.Sp
-If you can get the precise version of libvirt you are using
-then that too is helpful.
-.IP "4. Submit a bug report." 4
-.IX Item "4. Submit a bug report."
-Go to <https://bugzilla.redhat.com/> and enter a new bug.
-Please describe the problem in as much detail as possible.
-.Sp
-Remember to include the version numbers (step 3) and the debug
-messages file (step 2).
-.IP "5. Assign the bug to rjones @ redhat.com" 4
-.IX Item "5. Assign the bug to rjones @ redhat.com"
-Assign or reassign the bug to \fBrjones @ redhat.com\fR (without the
-spaces). You can also send me an email with the bug number if you
-want a faster response.
+++ /dev/null
-NAME
- virt-top - 'top'-like utility for virtualization stats
-
-SUMMARY
- virt-top [-options]
-
-DESCRIPTION
- virt-top is a top(1)-like utility for showing stats of virtualized
- domains. Many keys and command line options are the same as for ordinary
- *top*.
-
- It uses libvirt so it is capable of showing stats across a variety of
- different virtualization systems.
-
-OPTIONS
- -1 Display physical CPUs by default (instead of domains). When virt-top
- is running, use the *1* key to toggle between physical CPUs and
- domains display.
-
- -2 Display network interfaces by default (instead of domains). When
- virt-top is running, use the *2* key to toggle between network
- interfaces and domains display.
-
- -3 Display block devices (virtual disks) by default (instead of
- domains). When virt-top is running, use the *3* key to toggle
- between block devices and domains display.
-
- -b Batch mode. In this mode keypresses are ignored.
-
- -c uri or --connect uri
- Connect to URI given. The default is to connect to the Xen
- hypervisor.
-
- To connect to QEMU/KVM you would normally do *-c qemu:///system*
-
- To connect to libvirtd on a remote machine you would normally do *-c
- xen://host/*
-
- Full details on connection URIs is available at
- <http://libvirt.org/uri.html>
-
- -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 *s* or *d* key.
-
- -n iterations
- Set the number of iterations to run. The default is to run
- continuously.
-
- -o sort
- Set the sort order to one of: cpu (sort by %CPU used), mem (sort by
- total memory), time (sort by total time), id (sort by domain ID),
- name (sort by domain name), netrx (sort by network received bytes),
- nettx (sort by network transmitted bytes), blockrdrq (sort by block
- device [disk] read requests), blockwrrq (sort by block device [disk]
- write requests).
-
- While virt-top is running you can change the sort order using keys
- *P* (cpu), *M* (memory), *T* (total time), *N* (domain ID), *F*
- (interactively select the sort field).
-
- -s Secure mode. Currently this does nothing.
-
- --hist-cpu secs
- Set the time in seconds between updates of the historical %CPU at
- the top right of the display.
-
- --csv file.csv
- Write the statistics to file *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 *README* file in the source
- distribution for details).
-
- To save space you can compress your CSV files (if your shell
- supports this feature, eg. *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
- *output.csv.00*, *output.csv.01* etc.
-
- virt-top --csv >(split -d -l 1000 - output.csv.)
-
- --no-csv-cpu
- Disable domain CPU stats in CSV output.
-
- --no-csv-block
- Disable domain block device stats in CSV output.
-
- --no-csv-net
- Disable domain network interface stats in CSV output.
-
- --debug filename
- Send debug and error messages to *filename*. To send error messages
- to syslog you can do:
-
- virt-top --debug >(logger -t virt-top)
-
- See also REPORTING BUGS below.
-
- --init-file filename
- Read *filename* as the init file instead of the default which is
- *$HOME/.virt-toprc*. See also INIT FILE below.
-
- --no-init-file
- Do not read any init file.
-
- --script
- Script mode. There will be no user interface. This is most useful
- when used together with the *--csv* and *-n* options.
-
- --stream
- Stream mode. All output is sent to stdout. This can be used from
- shell scripts etc. There is no user interface.
-
- --block-in-bytes
- Show I/O statistics in Bytes. Default is shown in the number of
- Requests.
-
- --end-time time
- The program will exit at the *time* given.
-
- The time may be given in one of the following formats:
-
- *YYYY-MM-DD HH:MM:SS*
- End time is the date and time given.
-
- *HH:MM:SS*
- End time is the time given, today.
-
- *+HH:MM:SS*
- End time is HH hours, MM minutes, SS seconds in the future
- (counted from the moment that program starts).
-
- *+secs*
- End time is *secs* seconds in the future.
-
- 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 *README* file in the source
- distribution for details).
-
- --help
- Display usage summary.
-
- --version
- Display version number and exit.
-
-KEYS
- Note that keys are case sensitive. For example use upper-case *P* (shift
- P) to sort by %CPU. *^* before a key means a Ctrl key, so *^L* is Ctrl
- L.
-
- *space* or *^L*
- Updates the display.
-
- *q* Quits the program.
-
- *h* Displays help.
-
- *s* or *d*
- Change the delay between screen updates.
-
- *B* Toggle Block I/O statistics so they are shown in either bytes or
- requests.
-
- *0* (number 0)
- Show the normal list of domains display.
-
- *1* (number 1)
- Toggle into showing physical CPUs. If pressed again toggles back to
- showing domains (the normal display).
-
- *2* Toggle into showing network interfaces. If pressed again toggles
- back to showing domains.
-
- *3* Toggle into showing block devices (virtual disks). If pressed again
- toggles back to showing domains.
-
- *P* Sort by %CPU.
-
- *M* Sort by total memory. Note that this shows the total memory
- allocated to the guest, not the memory being used.
-
- *T* Sort by total time.
-
- *N* Sort by domain ID.
-
- *F* Select the sort field interactively (there are other sort fields you
- can choose using this key).
-
- *W* This creates or overwrites the init file with the current settings.
-
- This key is disabled if *--no-init-file* was specified on the
- command line or if *overwrite-init-file false* is given in the init
- file.
-
-INIT FILE
- When virt-top starts up, it reads initial settings from the file
- *.virt-toprc* in the user's home directory.
-
- The name of this file may be overridden using the *--init-file filename*
- command line option or may be disabled entirely using *--no-init-file*.
-
- The init file has a simple format. Blank lines and comments beginning
- with *#* are ignored. Everything else is a set of *key value* pairs,
- described below.
-
- display *task|pcpu|block|net*
- Sets the major display mode to one of *task* (tasks, the default),
- *pcpu* (physical CPUs), *block* (block devices), or *net* (network
- interfaces).
-
- delay *secs*
- Sets the delay between display updates in seconds.
-
- hist-cpu *secs*
- Sets the historical CPU delay in seconds.
-
- iterations *n*
- Sets the number of iterations to run before we exit. Setting this to
- *-1* means to run continuously.
-
- sort *cpu|mem|time|id|name|...*
- Sets the sort order. The option names are the same as for the
- command line *-o* option.
-
- connect *uri*
- Sets the default connection URI.
-
- debug *filename*
- Sets the default filename to use for debug and error messages.
-
- csv *filename*
- Enables CSV output to the named file.
-
- csv-cpu *true|false*
- Enable or disable domain CPU stats in CSV output.
-
- csv-block *true|false*
- Enable or disable domain block device stats in CSV output.
-
- csv-net *true|false*
- Enable or disable domain network interface stats in CSV output.
-
- batch *true|false*
- Sets batch mode.
-
- secure *true|false*
- Sets secure mode.
-
- script *true|false*
- Sets script mode.
-
- stream *true|false*
- Sets stream mode.
-
- block-in-bytes *true|false*
- Show block device statistics in bytes.
-
- end-time *time*
- Set the time at which the program exits. See above for the time
- formats supported.
-
- overwrite-init-file *false*
- If set to *false* then the *W* key will not overwrite the init file.
-
- 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.
-
-NOTES
- 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.
-
- 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.
-
-SEE ALSO
- top(1), virsh(1), <http://www.libvirt.org/ocaml/>,
- <http://www.libvirt.org/>, <http://people.redhat.com/~rjones/>,
- <http://caml.inria.fr/>
-
-AUTHORS
- Richard W.M. Jones <rjones @ redhat . com>
-
-COPYRIGHT
- (C) Copyright 2007-2011 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.
-
-REPORTING BUGS
- Bugs can be viewed on the Red Hat Bugzilla page:
- <https://bugzilla.redhat.com/>.
-
- If you find a bug in virt-top, please follow these steps to report it:
-
- 1. Check for existing bug reports
- Go to <https://bugzilla.redhat.com/> and search for similar bugs.
- Someone may already have reported the same bug, and they may even
- have fixed it.
-
- 2. Capture debug and error messages
- Run
-
- virt-top --debug virt-top.log
-
- and keep *virt-top.log*. It contains error messages which you should
- submit with your bug report.
-
- 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.
-
- 4. Submit a bug report.
- Go to <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).
-
- 5. Assign the bug to rjones @ redhat.com
- Assign or reassign the bug to rjones @ redhat.com (without the
- spaces). You can also send me an email with the bug number if you
- want a faster response.
-
git.annexia.org / virt-top.git / commitdiff