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 URI given. The default is to connect to the Xen
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.
55 =item B<-n iterations>
57 Set the number of iterations to run. The default
58 is to run continuously.
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).
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).
80 Secure mode. Currently this does nothing.
82 =item B<--hist-cpu secs>
84 Set the time in seconds between updates of the historical
85 %CPU at the top right of the display.
87 =item B<--csv file.csv>
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.
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).
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
102 To save space you can compress your CSV files (if your shell supports
103 this feature, eg. I<bash>):
105 virt-top --csv >(gzip -9 > output.csv.gz)
107 You can use a similar trick to split the CSV file up. In this example
108 the CSV file is split every 1000 lines into files called
109 I<output.csv.00>, I<output.csv.01> etc.
111 virt-top --csv >(split -d -l 1000 - output.csv.)
113 =item B<--no-csv-cpu>
115 Disable domain CPU stats in CSV output.
117 =item B<--no-csv-block>
119 Disable domain block device stats in CSV output.
121 =item B<--no-csv-net>
123 Disable domain network interface stats in CSV output.
125 =item B<--debug filename>
127 Send debug and error messages to I<filename>.
128 To send error messages to syslog you can do:
130 virt-top --debug >(logger -t virt-top)
132 See also REPORTING BUGS below.
134 =item B<--init-file filename>
136 Read I<filename> as the init file instead of the default which is
137 I<$HOME/.virt-toprc>. See also INIT FILE below.
139 =item B<--no-init-file>
141 Do not read any init file.
145 Script mode. There will be no user interface. This is most useful
146 when used together with the I<--csv> and I<-n> options.
148 =item B<--end-time time>
150 The program will exit at the I<time> given.
152 The time may be given in one of the following formats:
156 =item I<YYYY-MM-DD HH:MM:SS>
158 End time is the date and time given.
162 End time is the time given, today.
166 End time is HH hours, MM minutes, SS seconds in the future (counted
167 from the moment that program starts).
171 End time is I<secs> seconds in the future.
175 For example to run the program for 3 minutes you could do:
177 virt-top --end-time +00:03:00
181 virt-top --end-time +180
183 Not every version of virt-top supports this option - it depends how the
184 program was compiled (see I<README> file in the source distribution
189 Display usage summary.
195 Note that keys are case sensitive. For example use upper-case I<P>
196 (shift P) to sort by %CPU. I<^> before a key means a Ctrl key, so
201 =item I<space> or I<^L>
215 Change the delay between screen updates.
217 =item I<0> (number 0)
219 Show the normal list of domains display.
221 =item I<1> (number 1)
223 Toggle into showing physical CPUs. If pressed
224 again toggles back to showing domains (the normal
229 Toggle into showing network interfaces. If pressed
230 again toggles back to showing domains.
234 Toggle into showing block devices (virtual disks). If pressed again
235 toggles back to showing domains.
255 Select the sort field interactively (there are other
256 sort fields you can choose using this key).
260 This creates or overwrites the init file with the current settings.
262 This key is disabled if I<--no-init-file> was specified on the
263 command line or if I<overwrite-init-file false> is given in
270 When virt-top starts up, it reads initial settings from the
271 file I<.virt-toprc> in the user's home directory.
273 The name of this file may be overridden using the I<--init-file
274 filename> command line option or may be disabled entirely using
277 The init file has a simple format. Blank lines and comments
278 beginning with I<#> are ignored. Everything else is a set of
279 I<key value> pairs, described below.
283 =item B<display> I<task|pcpu|block|net>
285 Sets the major display mode to one of I<task> (tasks, the
286 default), I<pcpu> (physical CPUs), I<block> (block devices),
287 or I<net> (network interfaces).
289 =item B<delay> I<secs>
291 Sets the delay between display updates in seconds.
293 =item B<hist-cpu> I<secs>
295 Sets the historical CPU delay in seconds.
297 =item B<iterations> I<n>
299 Sets the number of iterations to run before we exit. Setting
300 this to I<-1> means to run continuously.
302 =item B<sort> I<cpu|mem|time|id|name|...>
304 Sets the sort order. The option names are the same as for
305 the command line I<-o> option.
307 =item B<connect> I<uri>
309 Sets the default connection URI.
311 =item B<debug> I<filename>
313 Sets the default filename to use for debug and error messages.
315 =item B<csv> I<filename>
317 Enables CSV output to the named file.
319 =item B<csv-cpu> I<true|false>
321 Enable or disable domain CPU stats in CSV output.
323 =item B<csv-block> I<true|false>
325 Enable or disable domain block device stats in CSV output.
327 =item B<csv-net> I<true|false>
329 Enable or disable domain network interface stats in CSV output.
331 =item B<batch> I<true|false>
335 =item B<secure> I<true|false>
339 =item B<script> I<true|false>
343 =item B<end-time> I<time>
345 Set the time at which the program exits. See above for the
346 time formats supported.
348 =item B<overwrite-init-file> I<false>
350 If set to I<false> then the I<W> key will not overwrite the
356 Note that in the current implementation, options specified in
357 the init file override options specified on the command line.
358 This is a bug and this behaviour may change in the future.
366 L<http://www.libvirt.org/>,
367 L<http://et.redhat.com/~rjones/>,
368 L<http://caml.inria.fr/>
372 Richard W.M. Jones <rjones @ redhat . com>
376 (C) Copyright 2007 Red Hat Inc., Richard W.M. Jones
379 This program is free software; you can redistribute it and/or modify
380 it under the terms of the GNU General Public License as published by
381 the Free Software Foundation; either version 2 of the License, or
382 (at your option) any later version.
384 This program is distributed in the hope that it will be useful,
385 but WITHOUT ANY WARRANTY; without even the implied warranty of
386 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
387 GNU General Public License for more details.
389 You should have received a copy of the GNU General Public License
390 along with this program; if not, write to the Free Software
391 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
393 =head1 REPORTING BUGS
395 Bugs can be viewed on the Red Hat Bugzilla page:
396 L<https://bugzilla.redhat.com/>.
398 If you find a bug in virt-top, please follow these steps to report it:
402 =item 1. Check for existing bug reports
404 Go to L<https://bugzilla.redhat.com/> and search for similar bugs.
405 Someone may already have reported the same bug, and they may even
408 =item 2. Capture debug and error messages
412 virt-top --debug virt-top.log
414 and keep I<virt-top.log>. It contains error messages which you
415 should submit with your bug report.
417 =item 3. Get version of virt-top and version of libvirt.
419 In virt-top, press the I<h> (help) key, and write down the version of
420 virt-top and the version of libvirt. They are shown in the first
423 =item 4. Submit a bug report.
425 Go to L<https://bugzilla.redhat.com/> and enter a new bug.
426 Please describe the problem in as much detail as possible.
428 Remember to include the version numbers (step 3) and the debug
429 messages file (step 2).
431 =item 5. Assign the bug to rjones @ redhat.com
433 Assign or reassign the bug to B<rjones @ redhat.com> (without the
434 spaces). You can also send me an email with the bug number if you
435 want a faster response.