virt-top/virt-top.txt

   1 NAME
   2     virt-top - 'top'-like utility for virtualization stats
   3
   4 SUMMARY
   5     virt-top [-options]
   6
   7 DESCRIPTION
   8     virt-top is a top(1)-like utility for showing stats of virtualized
   9     domains. Many keys and command line options are the same as for ordinary
  10     *top*.
  11
  12     It uses libvirt so it is capable of showing stats across a variety of
  13     different virtualization systems.
  14
  15 OPTIONS
  16     -1  Display physical CPUs by default (instead of domains). When virt-top
  17         is running, use the *1* key to toggle between physical CPUs and
  18         domains display.
  19
  20     -2  Display network interfaces by default (instead of domains). When
  21         virt-top is running, use the *2* key to toggle between network
  22         interfaces and domains display.
  23
  24     -3  Display block devices (virtual disks) by default (instead of
  25         domains). When virt-top is running, use the *3* key to toggle
  26         between block devices and domains display.
  27
  28     -b  Batch mode. In this mode keypresses are ignored.
  29
  30     -c uri or --connect uri
  31         Connect to URI given. The default is to connect to the Xen
  32         hypervisor.
  33
  34     -d delay
  35         Set the delay between screen updates in seconds. The default is 3.0
  36         seconds. You can change this while virt-top is running by pressing
  37         either *s* or *d* key.
  38
  39     -n iterations
  40         Set the number of iterations to run. The default is to run
  41         continuously.
  42
  43     -o sort
  44         Set the sort order to one of: cpu (sort by %CPU used), mem (sort by
  45         memory used), time (sort by total time), id (sort by domain ID),
  46         name (sort by domain name), netrx (sort by network received bytes),
  47         nettx (sort by network transmitted bytes), blockrdrq (sort by block
  48         device [disk] read requests), blockwrrq (sort by block device [disk]
  49         write requests).
  50
  51         While virt-top is running you can change the sort order using keys
  52         *P* (cpu), *M* (memory), *T* (total time), *N* (domain ID), *F*
  53         (interactively select the sort field).
  54
  55     -s  Secure mode. Currently this does nothing.
  56
  57     --hist-cpu secs
  58         Set the time in seconds between updates of the historical %CPU at
  59         the top right of the display.
  60
  61     --csv file.csv
  62         Write the statistics to file *file.csv*. First a header is written
  63         showing the statistics being recorded in each column, then one line
  64         is written for each screen update. The CSV file can be loaded
  65         directly by most spreadsheet programs.
  66
  67         Currently the statistics which this records vary between releases of
  68         virt-top (but the column headers will stay the same, so you can use
  69         those to process the CSV file).
  70
  71         Not every version of virt-top supports CSV output - it depends how
  72         the program was compiled (see *README* file in the source
  73         distribution for details).
  74
  75     --no-csv-cpu
  76         Disable domain CPU stats in CSV output.
  77
  78     --no-csv-block
  79         Disable domain block device stats in CSV output.
  80
  81     --no-csv-net
  82         Disable domain network interface stats in CSV output.
  83
  84     --debug filename
  85         Send debug and error messages to *filename*. To send error messages
  86         to syslog you can do:
  87
  88          virt-top --debug >(logger -t virt-top)
  89
  90         See also REPORTING BUGS below.
  91
  92     --init-file filename
  93         Read *filename* as the init file instead of the default which is
  94         *$HOME/.virt-toprc*. See also INIT FILE below.
  95
  96     --no-init-file
  97         Do not read any init file.
  98
  99     --script
 100         Script mode. There will be no user interface. This is most useful
 101         when used together with the *--csv* and *-n* options.
 102
 103     --help
 104         Display usage summary.
 105
 106 KEYS
 107     Note that keys are case sensitive. For example use upper-case *P* (shift
 108     P) to sort by %CPU. *^* before a key means a Ctrl key, so *^L* is Ctrl
 109     L.
 110
 111     *space* or *^L*
 112         Updates the display.
 113
 114     *q* Quits the program.
 115
 116     *h* Displays help.
 117
 118     *s* or *d*
 119         Change the delay between screen updates.
 120
 121     *0* (number 0)
 122         Show the normal list of domains display.
 123
 124     *1* (number 1)
 125         Toggle into showing physical CPUs. If pressed again toggles back to
 126         showing domains (the normal display).
 127
 128     *2* Toggle into showing network interfaces. If pressed again toggles
 129         back to showing domains.
 130
 131     *3* Toggle into showing block devices (virtual disks). If pressed again
 132         toggles back to showing domains.
 133
 134     *P* Sort by %CPU.
 135
 136     *M* Sort by memory.
 137
 138     *T* Sort by total time.
 139
 140     *N* Sort by domain ID.
 141
 142     *F* Select the sort field interactively (there are other sort fields you
 143         can choose using this key).
 144
 145     *W* This creates or overwrites the init file with the current settings.
 146
 147         This key is disabled if *--no-init-file* was specified on the
 148         command line or if *overwrite-init-file false* is given in the init
 149         file.
 150
 151 INIT FILE
 152     When virt-top starts up, it reads initial settings from the file
 153     *.virt-toprc* in the user's home directory.
 154
 155     The name of this file may be overridden using the *--init-file filename*
 156     command line option or may be disabled entirely using *--no-init-file*.
 157
 158     The init file has a simple format. Blank lines and comments beginning
 159     with *#* are ignored. Everything else is a set of *key value* pairs,
 160     described below.
 161
 162     display *task|pcpu|block|net*
 163         Sets the major display mode to one of *task* (tasks, the default),
 164         *pcpu* (physical CPUs), *block* (block devices), or *net* (network
 165         interfaces).
 166
 167     delay *secs*
 168         Sets the delay between display updates in seconds.
 169
 170     hist-cpu *secs*
 171         Sets the historical CPU delay in seconds.
 172
 173     iterations *n*
 174         Sets the number of iterations to run before we exit. Setting this to
 175         *-1* means to run continuously.
 176
 177     sort *cpu|mem|time|id|name|...*
 178         Sets the sort order. The option names are the same as for the
 179         command line *-o* option.
 180
 181     connect *uri*
 182         Sets the default connection URI.
 183
 184     debug *filename*
 185         Sets the default filename to use for debug and error messages.
 186
 187     csv *filename*
 188         Enables CSV output to the named file.
 189
 190     csv-cpu *true|false*
 191         Enable or disable domain CPU stats in CSV output.
 192
 193     csv-block *true|false*
 194         Enable or disable domain block device stats in CSV output.
 195
 196     csv-net *true|false*
 197         Enable or disable domain network interface stats in CSV output.
 198
 199     batch *true|false*
 200         Sets batch mode.
 201
 202     secure *true|false*
 203         Sets secure mode.
 204
 205     script *true|false*
 206         Sets script mode.
 207
 208     overwrite-init-file *false*
 209         If set to *false* then the *W* key will not overwrite the init file.
 210
 211     Note that in the current implementation, options specified in the init
 212     file override options specified on the command line. This is a bug and
 213     this behaviour may change in the future.
 214
 215 SEE ALSO
 216     top(1), virsh(1), xm(1), xentop(1), <http://www.libvirt.org/>,
 217     <http://et.redhat.com/~rjones/>, <http://caml.inria.fr/>
 218
 219 AUTHORS
 220     Richard W.M. Jones <rjones @ redhat . com>
 221
 222 COPYRIGHT
 223     (C) Copyright 2007 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
 224
 225     This program is free software; you can redistribute it and/or modify it
 226     under the terms of the GNU General Public License as published by the
 227     Free Software Foundation; either version 2 of the License, or (at your
 228     option) any later version.
 229
 230     This program is distributed in the hope that it will be useful, but
 231     WITHOUT ANY WARRANTY; without even the implied warranty of
 232     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 233     Public License for more details.
 234
 235     You should have received a copy of the GNU General Public License along
 236     with this program; if not, write to the Free Software Foundation, Inc.,
 237     675 Mass Ave, Cambridge, MA 02139, USA.
 238
 239 REPORTING BUGS
 240     Bugs can be viewed on the Red Hat Bugzilla page:
 241     <https://bugzilla.redhat.com/>.
 242
 243     If you find a bug in virt-top, please follow these steps to report it:
 244
 245     1. Check for existing bug reports
 246         Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 247         Someone may already have reported the same bug, and they may even
 248         have fixed it.
 249
 250     2. Capture debug and error messages
 251         Run
 252
 253          virt-top --debug virt-top.log
 254
 255         and keep *virt-top.log*. It contains error messages which you should
 256         submit with your bug report.
 257
 258     3. Get version of virt-top and version of libvirt.
 259         In virt-top, press the *h* (help) key, and write down the version of
 260         virt-top and the version of libvirt. They are shown in the first
 261         line.
 262
 263     4. Submit a bug report.
 264         Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
 265         describe the problem in as much detail as possible.
 266
 267         Remember to include the version numbers (step 3) and the debug
 268         messages file (step 2).
 269
 270     5. Assign the bug to rjones @ redhat.com
 271         Assign or reassign the bug to rjones @ redhat.com (without the
 272         spaces). You can also send me an email with the bug number if you
 273         want a faster response.
 274