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