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