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 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 --version
198 Display version number and exit.
199
201 Note that keys are case sensitive. For example use upper-case P (shift
202 P) to sort by %CPU. ^ before a key means a Ctrl key, so ^L is Ctrl L.
203 space or ^L
205 Updates the display.
206 q Quits the program.
208 h Displays help.
210 s or d
212 Change the delay between screen updates.
213 B Toggle Block I/O statistics so they are shown in either bytes or
215 requests.
216 0 (number 0)
218 Show the normal list of domains display.
219 1 (number 1)
221 Toggle into showing physical CPUs. If pressed again toggles back
222 to showing domains (the normal display).
223 2 Toggle into showing network interfaces. If pressed again toggles
225 back to showing domains.
226 3 Toggle into showing block devices (virtual disks). If pressed
228 again toggles back to showing domains.
229 P Sort by %CPU.
231 M Sort by total memory. Note that this shows the total memory
233 allocated to the guest, not the memory being used.
234 T Sort by total time.
236 N Sort by domain ID.
238 F Select the sort field interactively (there are other sort fields
240 you can choose using this key).
241 W This creates or overwrites the init file with the current settings.
243 This key is disabled if --no-init-file was specified on the command
245 line or if overwrite-init-file false is given in the init file.
246
248 When virt-top starts up, it reads initial settings from the file
249 .virt-toprc in the user's home directory.
250 The name of this file may be overridden using the --init-file filename
252 command line option or may be disabled entirely using --no-init-file.
253 The init file has a simple format. Blank lines and comments beginning
255 with # are ignored. Everything else is a set of key value pairs,
256 described below.
257 display task|pcpu|block|net
259 Sets the major display mode to one of task (tasks, the default),
260 pcpu (physical CPUs), block (block devices), or net (network
261 interfaces).
262 delay secs
264 Sets the delay between display updates in seconds.
265 hist-cpu secs
267 Sets the historical CPU delay in seconds.
268 iterations n
270 Sets the number of iterations to run before we exit. Setting this
271 to -1 means to run continuously.
272 sort cpu|mem|time|id|name|...
274 Sets the sort order. The option names are the same as for the
275 command line -o option.
276 connect uri
278 Sets the default connection URI.
279 debug filename
281 Sets the default filename to use for debug and error messages.
282 csv filename
284 Enables CSV output to the named file.
285 csv-cpu true|false
287 Enable or disable domain CPU stats in CSV output.
288 csv-mem true|false
290 Enable or disable domain memory stats in CSV output.
291 csv-block true|false
293 Enable or disable domain block device stats in CSV output.
294 csv-net true|false
296 Enable or disable domain network interface stats in CSV output.
297 batch true|false
299 Sets batch mode.
300 secure true|false
302 Sets secure mode.
303 script true|false
305 Sets script mode.
306 stream true|false
308 Sets stream mode.
309 block-in-bytes true|false
311 Show block device statistics in bytes.
312 end-time time
314 Set the time at which the program exits. See above for the time
315 formats supported.
316 overwrite-init-file false
318 If set to false then the W key will not overwrite the init file.
319 Note that in the current implementation, options specified in the init
321 file override options specified on the command line. This is a bug and
322 this behaviour may change in the future.
323
325 %CPU
326 Percentage of CPU used. As with top(1), 100% means that all
327 physical CPUs are being fully used.
328 DEVICE
330 The block device name.
331 DOMAIN
333 NAME
334 The name of the libvirt domain.
335 ID The libvirt domain ID.
337 INTERFACE
339 The network interface name.
340 %MEM
342 The percentage of host memory assigned to the guest.
343 PHYCPU
345 The physical CPU.
346 RDBY
348 Disk bytes read since last displayed.
349 RDRQ
351 Disk read requests since last displayed.
352 RXBY
354 Network bytes received since last displayed.
355 RXPK
357 Network packets received since last displayed.
358 S The state of the domain, one of:
360 ? Unknown.
362 R Running.
364 S Blocked.
366 P Paused.
368 D
370 O Shutdown.
371 X Crashed.
373 TIME
375 Total CPU time used.
376 TXBY
378 Network bytes transmitted since last displayed.
379 TXPK
381 Network packets transmitted since last displayed.
382 WRBY
384 Disk bytes written since last displayed.
385 WRRQ
387 Disk write requests since last displayed.
388
390 Block I/O statistics
391 This I/O value is the amount of I/O since the previous iteration of
392 virt-top. To calculate speed of I/O, you should divide the number by
393 delay secs.
394 NETWORK RX BYTES AND PACKETS
396 Libvirt/virt-top has no way to know that a packet transmitted to a
397 guest was received (eg. if the guest is not listening). In the network
398 RX stats, virt-top reports the packets transmitted to the guest, on the
399 basis that the guest might receive them.
400 In particular this includes broadcast packets. Because of the way that
402 Linux bridges work, if the guest is connected to a bridge, it will
403 probably see a steady "background noise" of RX packets even when the
404 network interface is idle or down. These are caused by STP packets
405 generated by the bridge.
406 DEBUGGING LIBVIRT ISSUES
408 virt-top tries to turn libvirt errors into informative messages.
409 However if libvirt initialization fails then this is not possible.
410 Instead you will get an obscure error like:
411 libvir: error : Unknown failure
413 Fatal error: exception Libvirt.Virterror(...)
414 To see the cause of libvirt errors in more detail, enable libvirt
416 debugging by setting this environment variable:
417 export LIBVIRT_DEBUG=1
419
421 top(1), virsh(1), <http://www.libvirt.org/ocaml/>,
422 <http://www.libvirt.org/>, <http://people.redhat.com/~rjones/>,
423 <http://caml.inria.fr/>
424
426 Richard W.M. Jones <rjones @ redhat . com>
427
429 (C) Copyright 2007-2012 Red Hat Inc., Richard W.M. Jones
430 http://libvirt.org/
431 This program is free software; you can redistribute it and/or modify it
433 under the terms of the GNU General Public License as published by the
434 Free Software Foundation; either version 2 of the License, or (at your
435 option) any later version.
436 This program is distributed in the hope that it will be useful, but
438 WITHOUT ANY WARRANTY; without even the implied warranty of
439 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
440 General Public License for more details.
441 You should have received a copy of the GNU General Public License along
443 with this program; if not, write to the Free Software Foundation, Inc.,
444 675 Mass Ave, Cambridge, MA 02139, USA.
445
447 Bugs can be viewed on the Red Hat Bugzilla page:
448 <https://bugzilla.redhat.com/>.
449 If you find a bug in virt-top, please follow these steps to report it:
451 1. Check for existing bug reports
453 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
454 Someone may already have reported the same bug, and they may even
455 have fixed it.
456 2. Capture debug and error messages
458 Run
459 virt-top --debug virt-top.log
461 and keep virt-top.log. It contains error messages which you should
463 submit with your bug report.
464 3. Get version of virt-top and version of libvirt.
466 Use:
467 virt-top --version
469 If you can get the precise version of libvirt you are using then
471 that too is helpful.
472 4. Submit a bug report.
474 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
475 describe the problem in as much detail as possible.
476 Remember to include the version numbers (step 3) and the debug
478 messages file (step 2).
479 5. Assign the bug to rjones @ redhat.com
481 Assign or reassign the bug to rjones @ redhat.com (without the
482 spaces). You can also send me an email with the bug number if you
483 want a faster response.
484virt-top-1.0.8 2018-04-15 VIRT-TOP(1)