3 virt-top - 'top'-like utility for virtualization stats
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
15 It uses libvirt so it is capable of showing stats across a variety of
16 different virtualization systems.
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.
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.
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.
42 Batch mode. In this mode keypresses are ignored.
44 =item B<-c uri> or B<--connect uri>
46 Connect to the libvirt URI given.
48 To connect to QEMU/KVM you would normally do I<-c qemu:///system>
50 To connect to Xen on the same host, do I<-c xen:///>
52 To connect to libvirtd on a remote machine you would normally do
53 I<-c qemu://host/system>
55 If this option is not given then virt-top connects by default
56 to whatever is the default hypervisor for libvirt, although
57 this can be overridden by setting environment variables.
59 See the libvirt documentation at L<http://libvirt.org/uri.html>
60 for further information.
64 Set the delay between screen updates in seconds.
65 The default is 3.0 seconds. You can change this
66 while virt-top is running by pressing either I<s> or I<d> key.
68 =item B<-n iterations>
70 Set the number of iterations to run. The default
71 is to run continuously.
75 Set the sort order to one of:
76 B<cpu> (sort by %CPU used),
77 B<mem> (sort by total memory),
78 B<time> (sort by total time),
79 B<id> (sort by domain ID),
80 B<name> (sort by domain name),
81 B<netrx> (sort by network received bytes),
82 B<nettx> (sort by network transmitted bytes),
83 B<blockrdrq> (sort by block device [disk] read requests),
84 B<blockwrrq> (sort by block device [disk] write requests).
86 While virt-top is running you can change the sort
87 order using keys I<P> (cpu), I<M> (memory),
88 I<T> (total time), I<N> (domain ID),
89 I<F> (interactively select the sort field).
93 Secure mode. Currently this does nothing.
95 =item B<--hist-cpu secs>
97 Set the time in seconds between updates of the historical
98 %CPU at the top right of the display.
100 =item B<--csv file.csv>
102 Write the statistics to file I<file.csv>. First a header is written
103 showing the statistics being recorded in each column, then one line is
104 written for each screen update. The CSV file can be loaded directly
105 by most spreadsheet programs.
107 Currently the statistics which this records vary between releases of
108 virt-top (but the column headers will stay the same, so you can use
109 those to process the CSV file).
111 Not every version of virt-top supports CSV output - it depends how the
112 program was compiled (see I<README> file in the source distribution
115 To save space you can compress your CSV files (if your shell supports
116 this feature, eg. I<bash>):
118 virt-top --csv >(gzip -9 > output.csv.gz)
120 You can use a similar trick to split the CSV file up. In this example
121 the CSV file is split every 1000 lines into files called
122 I<output.csv.00>, I<output.csv.01> etc.
124 virt-top --csv >(split -d -l 1000 - output.csv.)
126 =item B<--no-csv-cpu>
128 Disable domain CPU stats in CSV output.
130 =item B<--no-csv-mem>
132 Disable domain memory stats in CSV output.
134 =item B<--no-csv-block>
136 Disable domain block device stats in CSV output.
138 =item B<--no-csv-net>
140 Disable domain network interface stats in CSV output.
142 =item B<--debug filename>
144 Send debug and error messages to I<filename>.
145 To send error messages to syslog you can do:
147 virt-top --debug >(logger -t virt-top)
149 See also REPORTING BUGS below.
151 =item B<--init-file filename>
153 Read I<filename> as the init file instead of the default which is
154 I<$HOME/.virt-toprc>. See also INIT FILE below.
156 =item B<--no-init-file>
158 Do not read any init file.
162 Script mode. There will be no user interface. This is most useful
163 when used together with the I<--csv> and I<-n> options.
167 Stream mode. All output is sent to stdout. This can be used from
168 shell scripts etc. There is no user interface.
170 =item B<--block-in-bytes>
172 Show I/O statistics in Bytes. Default is shown in the number of Requests.
174 =item B<--end-time time>
176 The program will exit at the I<time> given.
178 The time may be given in one of the following formats:
182 =item I<YYYY-MM-DD HH:MM:SS>
184 End time is the date and time given.
188 End time is the time given, today.
192 End time is HH hours, MM minutes, SS seconds in the future (counted
193 from the moment that program starts).
197 End time is I<secs> seconds in the future.
201 For example to run the program for 3 minutes you could do:
203 virt-top --end-time +00:03:00
207 virt-top --end-time +180
209 Not every version of virt-top supports this option - it depends how the
210 program was compiled (see I<README> file in the source distribution
215 Display usage summary.
219 Display version number and exit.
225 Note that keys are case sensitive. For example use upper-case I<P>
226 (shift P) to sort by %CPU. I<^> before a key means a Ctrl key, so
231 =item I<space> or I<^L>
245 Change the delay between screen updates.
249 Toggle Block I/O statistics so they are shown in either bytes or requests.
251 =item I<0> (number 0)
253 Show the normal list of domains display.
255 =item I<1> (number 1)
257 Toggle into showing physical CPUs. If pressed
258 again toggles back to showing domains (the normal
263 Toggle into showing network interfaces. If pressed
264 again toggles back to showing domains.
268 Toggle into showing block devices (virtual disks). If pressed again
269 toggles back to showing domains.
277 Sort by total memory. Note that this shows the total memory
278 allocated to the guest, not the memory being used.
290 Select the sort field interactively (there are other
291 sort fields you can choose using this key).
295 This creates or overwrites the init file with the current settings.
297 This key is disabled if I<--no-init-file> was specified on the
298 command line or if I<overwrite-init-file false> is given in
305 When virt-top starts up, it reads initial settings from the
306 file I<.virt-toprc> in the user's home directory.
308 The name of this file may be overridden using the I<--init-file
309 filename> command line option or may be disabled entirely using
312 The init file has a simple format. Blank lines and comments
313 beginning with I<#> are ignored. Everything else is a set of
314 I<key value> pairs, described below.
318 =item B<display> I<task|pcpu|block|net>
320 Sets the major display mode to one of I<task> (tasks, the
321 default), I<pcpu> (physical CPUs), I<block> (block devices),
322 or I<net> (network interfaces).
324 =item B<delay> I<secs>
326 Sets the delay between display updates in seconds.
328 =item B<hist-cpu> I<secs>
330 Sets the historical CPU delay in seconds.
332 =item B<iterations> I<n>
334 Sets the number of iterations to run before we exit. Setting
335 this to I<-1> means to run continuously.
337 =item B<sort> I<cpu|mem|time|id|name|...>
339 Sets the sort order. The option names are the same as for
340 the command line I<-o> option.
342 =item B<connect> I<uri>
344 Sets the default connection URI.
346 =item B<debug> I<filename>
348 Sets the default filename to use for debug and error messages.
350 =item B<csv> I<filename>
352 Enables CSV output to the named file.
354 =item B<csv-cpu> I<true|false>
356 Enable or disable domain CPU stats in CSV output.
358 =item B<csv-mem> I<true|false>
360 Enable or disable domain memory stats in CSV output.
362 =item B<csv-block> I<true|false>
364 Enable or disable domain block device stats in CSV output.
366 =item B<csv-net> I<true|false>
368 Enable or disable domain network interface stats in CSV output.
370 =item B<batch> I<true|false>
374 =item B<secure> I<true|false>
378 =item B<script> I<true|false>
382 =item B<stream> I<true|false>
386 =item B<block-in-bytes> I<true|false>
388 Show block device statistics in bytes.
390 =item B<end-time> I<time>
392 Set the time at which the program exits. See above for the
393 time formats supported.
395 =item B<overwrite-init-file> I<false>
397 If set to I<false> then the I<W> key will not overwrite the
402 Note that in the current implementation, options specified in
403 the init file override options specified on the command line.
404 This is a bug and this behaviour may change in the future.
408 =head2 Block I/O statistics
410 This I/O value is the amount of I/O since the previous iteration
411 of virt-top. To calculate speed of I/O, you should divide
412 the number by delay secs.
414 =head2 NETWORK RX BYTES AND PACKETS
416 Libvirt/virt-top has no way to know that a packet transmitted to a
417 guest was received (eg. if the guest is not listening). In the
418 network RX stats, virt-top reports the packets transmitted to the
419 guest, on the basis that the guest might receive them.
421 In particular this includes broadcast packets. Because of the way
422 that Linux bridges work, if the guest is connected to a bridge, it
423 will probably see a steady "background noise" of RX packets even when
424 the network interface is idle or down. These are caused by STP
425 packets generated by the bridge.
427 =head2 DEBUGGING LIBVIRT ISSUES
429 virt-top tries to turn libvirt errors into informative messages.
430 However if libvirt initialization fails then this is not possible.
431 Instead you will get an obscure error like:
433 libvir: error : Unknown failure
434 Fatal error: exception Libvirt.Virterror(...)
436 To see the cause of libvirt errors in more detail, enable libvirt
437 debugging by setting this environment variable:
439 export LIBVIRT_DEBUG=1
445 L<http://www.libvirt.org/ocaml/>,
446 L<http://www.libvirt.org/>,
447 L<http://people.redhat.com/~rjones/>,
448 L<http://caml.inria.fr/>
452 Richard W.M. Jones <rjones @ redhat . com>
456 (C) Copyright 2007-2011 Red Hat Inc., Richard W.M. Jones
459 This program is free software; you can redistribute it and/or modify
460 it under the terms of the GNU General Public License as published by
461 the Free Software Foundation; either version 2 of the License, or
462 (at your option) any later version.
464 This program is distributed in the hope that it will be useful,
465 but WITHOUT ANY WARRANTY; without even the implied warranty of
466 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
467 GNU General Public License for more details.
469 You should have received a copy of the GNU General Public License
470 along with this program; if not, write to the Free Software
471 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
473 =head1 REPORTING BUGS
475 Bugs can be viewed on the Red Hat Bugzilla page:
476 L<https://bugzilla.redhat.com/>.
478 If you find a bug in virt-top, please follow these steps to report it:
482 =item 1. Check for existing bug reports
484 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
485 Someone may already have reported the same bug, and they may even
488 =item 2. Capture debug and error messages
492 virt-top --debug virt-top.log
494 and keep I<virt-top.log>. It contains error messages which you
495 should submit with your bug report.
497 =item 3. Get version of virt-top and version of libvirt.
503 If you can get the precise version of libvirt you are using
504 then that too is helpful.
506 =item 4. Submit a bug report.
508 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
509 Please describe the problem in as much detail as possible.
511 Remember to include the version numbers (step 3) and the debug
512 messages file (step 2).
514 =item 5. Assign the bug to rjones @ redhat.com
516 Assign or reassign the bug to B<rjones @ redhat.com> (without the
517 spaces). You can also send me an email with the bug number if you
518 want a faster response.