+++ /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 / blobdiff