virt-top/virt-top.pod

   1 =head1 NAME
   2
   3 virt-top - 'top'-like utility for virtualization stats
   4
   5 =head1 SUMMARY
   6
   7 virt-top [-options]
   8
   9 =head1 DESCRIPTION
  10
  11 virt-top is a L<top(1)>-like utility for showing stats of virtualized
  12 domains.  Many keys and command line options are the same as for
  13 ordinary I<top>.
  14
  15 It uses libvirt so it is capable of showing stats across a variety of
  16 different virtualization systems.
  17
  18 =head1 OPTIONS
  19
  20 =over 4
  21
  22 =item B<-1>
  23
  24 Display physical CPUs by default (instead of domains).
  25 When virt-top is running, use the I<1> key to toggle
  26 between physical CPUs and domains display.
  27
  28 =item B<-2>
  29
  30 Display network interfaces by default (instead of domains).
  31 When virt-top is running, use the I<2> key to toggle
  32 between network interfaces and domains display.
  33
  34 =item B<-3>
  35
  36 Display block devices (virtual disks) by default (instead of domains).
  37 When virt-top is running, use the I<3> key to toggle
  38 between block devices and domains display.
  39
  40 =item B<-b>
  41
  42 Batch mode.  In this mode keypresses are ignored.
  43
  44 =item B<-c uri> or B<--connect uri>
  45
  46 Connect to URI given.  The default is to connect to the Xen
  47 hypervisor.
  48
  49 =item B<-d delay>
  50
  51 Set the delay between screen updates in seconds.
  52 The default is 3.0 seconds.  You can change this
  53 while virt-top is running by pressing either I<s> or I<d> key.
  54
  55 =item B<-n iterations>
  56
  57 Set the number of iterations to run.  The default
  58 is to run continuously.
  59
  60 =item B<-o sort>
  61
  62 Set the sort order to one of:
  63 B<cpu> (sort by %CPU used),
  64 B<mem> (sort by memory used),
  65 B<time> (sort by total time),
  66 B<id> (sort by domain ID),
  67 B<name> (sort by domain name),
  68 B<netrx> (sort by network received bytes),
  69 B<nettx> (sort by network transmitted bytes),
  70 B<blockrdrq> (sort by block device [disk] read requests),
  71 B<blockwrrq> (sort by block device [disk] write requests).
  72
  73 While virt-top is running you can change the sort
  74 order using keys I<P> (cpu), I<M> (memory),
  75 I<T> (total time), I<N> (domain ID),
  76 I<F> (interactively select the sort field).
  77
  78 =item B<-s>
  79
  80 Secure mode.  Currently this does nothing.
  81
  82 =item B<--hist-cpu secs>
  83
  84 Set the time in seconds between updates of the historical
  85 %CPU at the top right of the display.
  86
  87 =item B<--csv file.csv>
  88
  89 Write the statistics to file I<file.csv>.  First a header is written
  90 showing the statistics being recorded in each column, then one line is
  91 written for each screen update.  The CSV file can be loaded directly
  92 by most spreadsheet programs.
  93
  94 Currently the statistics which this records vary between releases of
  95 virt-top (but the column headers will stay the same, so you can use
  96 those to process the CSV file).
  97
  98 Not every version of virt-top supports CSV output - it depends how the
  99 program was compiled (see I<README> file in the source distribution
 100 for details).
 101
 102 =item B<--debug filename>
 103
 104 Send debug and error messages to I<filename>.
 105 To send error messages to syslog you can do:
 106
 107  virt-top --debug >(logger -t virt-top)
 108
 109 See also REPORTING BUGS below.
 110
 111 =item B<--help>
 112
 113 Display usage summary.
 114
 115 =back
 116
 117 =head1 KEYS
 118
 119 Note that keys are case sensitive.  For example use upper-case I<P>
 120 (shift P) to sort by %CPU.  I<^> before a key means a Ctrl key, so
 121 I<^L> is Ctrl L.
 122
 123 =over 4
 124
 125 =item I<space> or I<^L>
 126
 127 Updates the display.
 128
 129 =item I<q>
 130
 131 Quits the program.
 132
 133 =item I<h>
 134
 135 Displays help.
 136
 137 =item I<s> or I<d>
 138
 139 Change the delay between screen updates.
 140
 141 =item I<0> (number 0)
 142
 143 Show the normal list of domains display.
 144
 145 =item I<1> (number 1)
 146
 147 Toggle into showing physical CPUs.  If pressed
 148 again toggles back to showing domains (the normal
 149 display).
 150
 151 =item I<2>
 152
 153 Toggle into showing network interfaces.  If pressed
 154 again toggles back to showing domains.
 155
 156 =item I<3>
 157
 158 Toggle into showing block devices (virtual disks).  If pressed again
 159 toggles back to showing domains.
 160
 161 =item I<P>
 162
 163 Sort by %CPU.
 164
 165 =item I<M>
 166
 167 Sort by memory.
 168
 169 =item I<T>
 170
 171 Sort by total time.
 172
 173 =item I<N>
 174
 175 Sort by domain ID.
 176
 177 =item I<F>
 178
 179 Select the sort field interactively (there are other
 180 sort fields you can choose using this key).
 181
 182 =back
 183
 184 =head1 SEE ALSO
 185
 186 L<top(1)>,
 187 L<virsh(1)>,
 188 L<xm(1)>,
 189 L<xentop(1)>,
 190 L<http://www.libvirt.org/>,
 191 L<http://et.redhat.com/~rjones/>,
 192 L<http://caml.inria.fr/>
 193
 194 =head1 AUTHORS
 195
 196 Richard W.M. Jones <rjones @ redhat . com>
 197
 198 =head1 REPORTING BUGS
 199
 200 Bugs can be viewed on the Red Hat Bugzilla page:
 201 L<https://bugzilla.redhat.com/>.
 202
 203 If you find a bug in virt-top, please follow these steps to report it:
 204
 205 =over 4
 206
 207 =item 1. Check for existing bug reports
 208
 209 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
 210 Someone may already have reported the same bug, and they may even
 211 have fixed it.
 212
 213 =item 2. Capture debug and error messages
 214
 215 Run
 216
 217  virt-top --debug virt-top.log
 218
 219 and keep I<virt-top.log>.  It contains error messages which you
 220 should submit with your bug report.
 221
 222 =item 3. Get version of virt-top and version of libvirt.
 223
 224 In virt-top, press the I<h> (help) key, and write down the version of
 225 virt-top and the version of libvirt.  They are shown in the first
 226 line.
 227
 228 =item 4. Submit a bug report.
 229
 230 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
 231 Please describe the problem in as much detail as possible.
 232
 233 Remember to include the version numbers (step 3) and the debug
 234 messages file (step 2).
 235
 236 =item 5. Assign the bug to rjones @ redhat.com
 237
 238 Assign or reassign the bug to B<rjones @ redhat.com> (without the
 239 spaces).  You can also send me an email with the bug number if you
 240 want a faster response.
 241
 242 =back
 243
 244 =end