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     --version
 156         Display version number and exit.
 157
 158 KEYS
 159     Note that keys are case sensitive. For example use upper-case *P* (shift
 160     P) to sort by %CPU. *^* before a key means a Ctrl key, so *^L* is Ctrl
 161     L.
 162
 163     *space* or *^L*
 164         Updates the display.
 165
 166     *q* Quits the program.
 167
 168     *h* Displays help.
 169
 170     *s* or *d*
 171         Change the delay between screen updates.
 172
 173     *0* (number 0)
 174         Show the normal list of domains display.
 175
 176     *1* (number 1)
 177         Toggle into showing physical CPUs. If pressed again toggles back to
 178         showing domains (the normal display).
 179
 180     *2* Toggle into showing network interfaces. If pressed again toggles
 181         back to showing domains.
 182
 183     *3* Toggle into showing block devices (virtual disks). If pressed again
 184         toggles back to showing domains.
 185
 186     *P* Sort by %CPU.
 187
 188     *M* Sort by memory.
 189
 190     *T* Sort by total time.
 191
 192     *N* Sort by domain ID.
 193
 194     *F* Select the sort field interactively (there are other sort fields you
 195         can choose using this key).
 196
 197     *W* This creates or overwrites the init file with the current settings.
 198
 199         This key is disabled if *--no-init-file* was specified on the
 200         command line or if *overwrite-init-file false* is given in the init
 201         file.
 202
 203 INIT FILE
 204     When virt-top starts up, it reads initial settings from the file
 205     *.virt-toprc* in the user's home directory.
 206
 207     The name of this file may be overridden using the *--init-file filename*
 208     command line option or may be disabled entirely using *--no-init-file*.
 209
 210     The init file has a simple format. Blank lines and comments beginning
 211     with *#* are ignored. Everything else is a set of *key value* pairs,
 212     described below.
 213
 214     display *task|pcpu|block|net*
 215         Sets the major display mode to one of *task* (tasks, the default),
 216         *pcpu* (physical CPUs), *block* (block devices), or *net* (network
 217         interfaces).
 218
 219     delay *secs*
 220         Sets the delay between display updates in seconds.
 221
 222     hist-cpu *secs*
 223         Sets the historical CPU delay in seconds.
 224
 225     iterations *n*
 226         Sets the number of iterations to run before we exit. Setting this to
 227         *-1* means to run continuously.
 228
 229     sort *cpu|mem|time|id|name|...*
 230         Sets the sort order. The option names are the same as for the
 231         command line *-o* option.
 232
 233     connect *uri*
 234         Sets the default connection URI.
 235
 236     debug *filename*
 237         Sets the default filename to use for debug and error messages.
 238
 239     csv *filename*
 240         Enables CSV output to the named file.
 241
 242     csv-cpu *true|false*
 243         Enable or disable domain CPU stats in CSV output.
 244
 245     csv-block *true|false*
 246         Enable or disable domain block device stats in CSV output.
 247
 248     csv-net *true|false*
 249         Enable or disable domain network interface stats in CSV output.
 250
 251     batch *true|false*
 252         Sets batch mode.
 253
 254     secure *true|false*
 255         Sets secure mode.
 256
 257     script *true|false*
 258         Sets script mode.
 259
 260     end-time *time*
 261         Set the time at which the program exits. See above for the time
 262         formats supported.
 263
 264     overwrite-init-file *false*
 265         If set to *false* then the *W* key will not overwrite the init file.
 266
 267     Note that in the current implementation, options specified in the init
 268     file override options specified on the command line. This is a bug and
 269     this behaviour may change in the future.
 270
 271 SEE ALSO
 272     top(1), virsh(1), xm(1), xentop(1), <http://www.libvirt.org/ocaml/>,
 273     <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
 274     <http://caml.inria.fr/>
 275
 276 AUTHORS
 277     Richard W.M. Jones <rjones @ redhat . com>
 278
 279 COPYRIGHT
 280     (C) Copyright 2007 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
 281
 282     This program is free software; you can redistribute it and/or modify it
 283     under the terms of the GNU General Public License as published by the
 284     Free Software Foundation; either version 2 of the License, or (at your
 285     option) any later version.
 286
 287     This program is distributed in the hope that it will be useful, but
 288     WITHOUT ANY WARRANTY; without even the implied warranty of
 289     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 290     Public License for more details.
 291
 292     You should have received a copy of the GNU General Public License along
 293     with this program; if not, write to the Free Software Foundation, Inc.,
 294     675 Mass Ave, Cambridge, MA 02139, USA.
 295
 296 REPORTING BUGS
 297     Bugs can be viewed on the Red Hat Bugzilla page:
 298     <https://bugzilla.redhat.com/>.
 299
 300     If you find a bug in virt-top, please follow these steps to report it:
 301
 302     1. Check for existing bug reports
 303         Go to <https://bugzilla.redhat.com/> and search for similar bugs.
 304         Someone may already have reported the same bug, and they may even
 305         have fixed it.
 306
 307     2. Capture debug and error messages
 308         Run
 309
 310          virt-top --debug virt-top.log
 311
 312         and keep *virt-top.log*. It contains error messages which you should
 313         submit with your bug report.
 314
 315     3. Get version of virt-top and version of libvirt.
 316         Use:
 317
 318          virt-top --version
 319
 320         If you can get the precise version of libvirt you are using then
 321         that too is helpful.
 322
 323     4. Submit a bug report.
 324         Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
 325         describe the problem in as much detail as possible.
 326
 327         Remember to include the version numbers (step 3) and the debug
 328         messages file (step 2).
 329
 330     5. Assign the bug to rjones @ redhat.com
 331         Assign or reassign the bug to rjones @ redhat.com (without the
 332         spaces). You can also send me an email with the bug number if you
 333         want a faster response.
 334