1VIRT-TOP(1) Virtualization Support VIRT-TOP(1)
2
6 virt-top - 'top'-like utility for virtualization stats
7
9 virt-top [-options]
10
12 virt-top is a top(1)-like utility for showing stats of virtualized
13 domains. Many keys and command line options are the same as for
14 ordinary top.
15 It uses libvirt so it is capable of showing stats across a variety of
17 different virtualization systems.
18
20 -1 Display physical CPUs by default (instead of domains).
21 Under each domain column, two numbers are shown. The first is the
23 percentage of the physical CPU used by the domain and the
24 hypervisor together. The second is the percentage used by just the
25 domain.
26 When virt-top is running, use the 1 key to toggle between physical
28 CPUs and domains display.
29 -2 Display network interfaces by default (instead of domains). When
31 virt-top is running, use the 2 key to toggle between network
32 interfaces and domains display.
33 -3 Display block devices (virtual disks) by default (instead of
35 domains). When virt-top is running, use the 3 key to toggle
36 between block devices and domains display.
37 -b Batch mode. In this mode keypresses are ignored.
39 -c uri or --connect uri
41 Connect to the libvirt URI given.
42 To connect to QEMU/KVM you would normally do -c qemu:///system
44 To connect to Xen on the same host, do -c xen:///
46 To connect to libvirtd on a remote machine you would normally do -c
48 qemu://host/system
49 If this option is not given then virt-top connects by default to
51 whatever is the default hypervisor for libvirt, although this can
52 be overridden by setting environment variables.
53 See the libvirt documentation at <http://libvirt.org/uri.html> for
55 further information.
56 -d delay
58 Set the delay between screen updates in seconds. The default is
59 3.0 seconds. You can change this while virt-top is running by
60 pressing either s or d key.
61 -n iterations
63 Set the number of iterations to run. The default is to run
64 continuously.
65 -o sort
67 Set the sort order to one of: cpu (sort by %CPU used), mem (sort by
68 total memory), time (sort by total time), id (sort by domain ID),
69 name (sort by domain name), netrx (sort by network received bytes),
70 nettx (sort by network transmitted bytes), blockrdrq (sort by block
71 device [disk] read requests), blockwrrq (sort by block device
72 [disk] write requests).
73 While virt-top is running you can change the sort order using keys
75 P (cpu), M (memory), T (total time), N (domain ID), F
76 (interactively select the sort field).
77 -s Secure mode. Currently this does nothing.
79 --hist-cpu secs
81 Set the time in seconds between updates of the historical %CPU at
82 the top right of the display.
83 --csv file.csv
85 Write the statistics to file file.csv. First a header is written
86 showing the statistics being recorded in each column, then one line
87 is written for each screen update. The CSV file can be loaded
88 directly by most spreadsheet programs.
89 Currently the statistics which this records vary between releases
91 of virt-top (but the column headers will stay the same, so you can
92 use those to process the CSV file).
93 Not every version of virt-top supports CSV output - it depends how
95 the program was compiled (see README file in the source
96 distribution for details).
97 To save space you can compress your CSV files (if your shell
99 supports this feature, eg. bash):
100 virt-top --csv >(gzip -9 > output.csv.gz)
102 You can use a similar trick to split the CSV file up. In this
104 example the CSV file is split every 1000 lines into files called
105 output.csv.00, output.csv.01 etc.
106 virt-top --csv >(split -d -l 1000 - output.csv.)
108 RHEL 6 provides a short Python script called "processcsv.py" which
110 can be used to post-process the CSV output. Run it like this:
111 virt-top --csv data.csv
113 processcsv.py < data.csv
114 This creates or overwrites the following files in the current
116 directory:
117 global.csv
119 domain<NNN>.csv
120 "global.csv" will contain the global data. One "domain<NNN>.csv"
122 file will also be created for each domain with ID "NNN", containing
123 the per-domain data.
124 --no-csv-cpu
126 Disable domain CPU stats in CSV output.
127 --no-csv-mem
129 Disable domain memory stats in CSV output.
130 --no-csv-block
132 Disable domain block device stats in CSV output.
133 --no-csv-net
135 Disable domain network interface stats in CSV output.
136 --debug filename
138 Send debug and error messages to filename. To send error messages
139 to syslog you can do:
140 virt-top --debug >(logger -t virt-top)
142 See also REPORTING BUGS below.
144 --init-file filename
146 Read filename as the init file instead of the default which is
147 $HOME/.virt-toprc. See also INIT FILE below.
148 --no-init-file
150 Do not read any init file.
151 --script
153 Script mode. There will be no user interface. This is most useful
154 when used together with the --csv and -n options.
155 --stream
157 Stream mode. All output is sent to stdout. This can be used from
158 shell scripts etc. There is no user interface.
159 --block-in-bytes
161 Show I/O statistics in Bytes. Default is shown in the number of
162 Requests.
163 --end-time time
165 The program will exit at the time given.
166 The time may be given in one of the following formats:
168 YYYY-MM-DD HH:MM:SS
170 End time is the date and time given.
171 HH:MM:SS
173 End time is the time given, today.
174 +HH:MM:SS
176 End time is HH hours, MM minutes, SS seconds in the future
177 (counted from the moment that program starts).
178 +secs
180 End time is secs seconds in the future.
181 For example to run the program for 3 minutes you could do:
183 virt-top --end-time +00:03:00
185 or:
187 virt-top --end-time +180
189 Not every version of virt-top supports this option - it depends how
191 the program was compiled (see README file in the source
192 distribution for details).
193 --help
195 Display usage summary.
196
198 Note that keys are case sensitive. For example use upper-case P (shift
199 P) to sort by %CPU. ^ before a key means a Ctrl key, so ^L is Ctrl L.
200 space or ^L
202 Updates the display.
203 q Quits the program.
205 h Displays help.
207 s or d
209 Change the delay between screen updates.
210 B Toggle Block I/O statistics so they are shown in either bytes or
212 requests.
213 0 (number 0)
215 Show the normal list of domains display.
216 1 (number 1)
218 Toggle into showing physical CPUs. If pressed again toggles back
219 to showing domains (the normal display).
220 2 Toggle into showing network interfaces. If pressed again toggles
222 back to showing domains.
223 3 Toggle into showing block devices (virtual disks). If pressed
225 again toggles back to showing domains.
226 P Sort by %CPU.
228 M Sort by total memory. Note that this shows the total memory
230 allocated to the guest, not the memory being used.
231 T Sort by total time.
233 N Sort by domain ID.
235 F Select the sort field interactively (there are other sort fields
237 you can choose using this key).
238 W This creates or overwrites the init file with the current settings.
240 This key is disabled if --no-init-file was specified on the command
242 line or if overwrite-init-file false is given in the init file.
243
245 When virt-top starts up, it reads initial settings from the file
246 .virt-toprc in the user's home directory.
247 The name of this file may be overridden using the --init-file filename
249 command line option or may be disabled entirely using --no-init-file.
250 The init file has a simple format. Blank lines and comments beginning
252 with # are ignored. Everything else is a set of key value pairs,
253 described below.
254 display task|pcpu|block|net
256 Sets the major display mode to one of task (tasks, the default),
257 pcpu (physical CPUs), block (block devices), or net (network
258 interfaces).
259 delay secs
261 Sets the delay between display updates in seconds.
262 hist-cpu secs
264 Sets the historical CPU delay in seconds.
265 iterations n
267 Sets the number of iterations to run before we exit. Setting this
268 to -1 means to run continuously.
269 sort cpu|mem|time|id|name|...
271 Sets the sort order. The option names are the same as for the
272 command line -o option.
273 connect uri
275 Sets the default connection URI.
276 debug filename
278 Sets the default filename to use for debug and error messages.
279 csv filename
281 Enables CSV output to the named file.
282 csv-cpu true|false
284 Enable or disable domain CPU stats in CSV output.
285 csv-mem true|false
287 Enable or disable domain memory stats in CSV output.
288 csv-block true|false
290 Enable or disable domain block device stats in CSV output.
291 csv-net true|false
293 Enable or disable domain network interface stats in CSV output.
294 batch true|false
296 Sets batch mode.
297 secure true|false
299 Sets secure mode.
300 script true|false
302 Sets script mode.
303 stream true|false
305 Sets stream mode.
306 block-in-bytes true|false
308 Show block device statistics in bytes.
309 end-time time
311 Set the time at which the program exits. See above for the time
312 formats supported.
313 overwrite-init-file false
315 If set to false then the W key will not overwrite the init file.
316 Note that in the current implementation, options specified in the init
318 file override options specified on the command line. This is a bug and
319 this behaviour may change in the future.
320
322 %CPU
323 Percentage of CPU used. As with top(1), 100% means that all
324 physical CPUs are being fully used.
325 DEVICE
327 The block device name.
328 DOMAIN
330 NAME
331 The name of the libvirt domain.
332 ID The libvirt domain ID.
334 INTERFACE
336 The network interface name.
337 %MEM
339 The percentage of host memory assigned to the guest.
340 PHYCPU
342 The physical CPU.
343 RDBY
345 Disk bytes read since last displayed.
346 RDRQ
348 Disk read requests since last displayed.
349 RXBY
351 Network bytes received since last displayed.
352 RXPK
354 Network packets received since last displayed.
355 S The state of the domain, one of:
357 ? Unknown.
359 R Running.
361 S Blocked.
363 P Paused.
365 D
367 O Shutdown.
368 X Crashed.
370 TIME
372 Total CPU time used.
373 TXBY
375 Network bytes transmitted since last displayed.
376 TXPK
378 Network packets transmitted since last displayed.
379 WRBY
381 Disk bytes written since last displayed.
382 WRRQ
384 Disk write requests since last displayed.
385
387 Block I/O statistics
388 This I/O value is the amount of I/O since the previous iteration of
389 virt-top. To calculate speed of I/O, you should divide the number by
390 delay secs.
391 NETWORK RX BYTES AND PACKETS
393 Libvirt/virt-top has no way to know that a packet transmitted to a
394 guest was received (eg. if the guest is not listening). In the network
395 RX stats, virt-top reports the packets transmitted to the guest, on the
396 basis that the guest might receive them.
397 In particular this includes broadcast packets. Because of the way that
399 Linux bridges work, if the guest is connected to a bridge, it will
400 probably see a steady "background noise" of RX packets even when the
401 network interface is idle or down. These are caused by STP packets
402 generated by the bridge.
403 DEBUGGING LIBVIRT ISSUES
405 virt-top tries to turn libvirt errors into informative messages.
406 However if libvirt initialization fails then this is not possible.
407 Instead you will get an obscure error like:
408 libvir: error : Unknown failure
410 Fatal error: exception Libvirt.Virterror(...)
411 To see the cause of libvirt errors in more detail, enable libvirt
413 debugging by setting this environment variable:
414 export LIBVIRT_DEBUG=1
416
418 top(1), virsh(1), <http://www.libvirt.org/ocaml/>,
419 <http://www.libvirt.org/>, <http://people.redhat.com/~rjones/>,
420 <http://caml.inria.fr/>
421
423 Richard W.M. Jones <rjones @ redhat . com>
424
426 (C) Copyright 2007-2012 Red Hat Inc., Richard W.M. Jones
427 http://libvirt.org/
428 This program is free software; you can redistribute it and/or modify it
430 under the terms of the GNU General Public License as published by the
431 Free Software Foundation; either version 2 of the License, or (at your
432 option) any later version.
433 This program is distributed in the hope that it will be useful, but
435 WITHOUT ANY WARRANTY; without even the implied warranty of
436 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
437 General Public License for more details.
438 You should have received a copy of the GNU General Public License along
440 with this program; if not, write to the Free Software Foundation, Inc.,
441 675 Mass Ave, Cambridge, MA 02139, USA.
442
444 Bugs can be viewed on the Red Hat Bugzilla page:
445 <https://bugzilla.redhat.com/>.
446 If you find a bug in virt-top, please follow these steps to report it:
448 1. Check for existing bug reports
450 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
451 Someone may already have reported the same bug, and they may even
452 have fixed it.
453 2. Capture debug and error messages
455 Run
456 virt-top --debug virt-top.log
458 and keep virt-top.log. It contains error messages which you should
460 submit with your bug report.
461 3. Get version of virt-top and version of libvirt.
463 In virt-top, press the h (help) key, and write down the version of
464 virt-top and the version of libvirt. They are shown in the first
465 line.
466 4. Submit a bug report.
468 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
469 describe the problem in as much detail as possible.
470 Remember to include the version numbers (step 3) and the debug
472 messages file (step 2).
473 5. Assign the bug to rjones @ redhat.com
475 Assign or reassign the bug to rjones @ redhat.com (without the
476 spaces). You can also send me an email with the bug number if you
477 want a faster response.
478virt-top-1.0.4 2013-02-21 VIRT-TOP(1)