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 To save space you can compress your CSV files (if your shell
95 supports this feature, eg. bash):
96 virt-top --csv >(gzip -9 > output.csv.gz)
98 You can use a similar trick to split the CSV file up. In this
100 example the CSV file is split every 1000 lines into files called
101 output.csv.00, output.csv.01 etc.
102 virt-top --csv >(split -d -l 1000 - output.csv.)
104 --no-csv-cpu
106 Disable domain CPU stats in CSV output.
107 --no-csv-mem
109 Disable domain memory stats in CSV output.
110 --no-csv-block
112 Disable domain block device stats in CSV output.
113 --no-csv-net
115 Disable domain network interface stats in CSV output.
116 --debug filename
118 Send debug and error messages to filename. To send error messages
119 to syslog you can do:
120 virt-top --debug >(logger -t virt-top)
122 See also REPORTING BUGS below.
124 --init-file filename
126 Read filename as the init file instead of the default which is
127 $HOME/.virt-toprc. See also INIT FILE below.
128 --no-init-file
130 Do not read any init file.
131 --script
133 Script mode. There will be no user interface. This is most useful
134 when used together with the --csv and -n options.
135 --stream
137 Stream mode. All output is sent to stdout. This can be used from
138 shell scripts etc. There is no user interface.
139 --block-in-bytes
141 Show I/O statistics in Bytes. Default is shown in the number of
142 Requests.
143 --end-time time
145 The program will exit at the time given.
146 The time may be given in one of the following formats:
148 YYYY-MM-DD HH:MM:SS
150 End time is the date and time given.
151 HH:MM:SS
153 End time is the time given, today.
154 +HH:MM:SS
156 End time is HH hours, MM minutes, SS seconds in the future
157 (counted from the moment that program starts).
158 +secs
160 End time is secs seconds in the future.
161 For example to run the program for 3 minutes you could do:
163 virt-top --end-time +00:03:00
165 or:
167 virt-top --end-time +180
169 Not every version of virt-top supports this option - it depends how
171 the program was compiled (see README file in the source
172 distribution for details).
173 --help
175 Display usage summary.
176 --version
178 Display version number and exit.
179
181 Note that keys are case sensitive. For example use upper-case P (shift
182 P) to sort by %CPU. ^ before a key means a Ctrl key, so ^L is Ctrl L.
183 space or ^L
185 Updates the display.
186 q Quits the program.
188 h Displays help.
190 s or d
192 Change the delay between screen updates.
193 B Toggle Block I/O statistics so they are shown in either bytes or
195 requests.
196 0 (number 0)
198 Show the normal list of domains display.
199 1 (number 1)
201 Toggle into showing physical CPUs. If pressed again toggles back
202 to showing domains (the normal display).
203 2 Toggle into showing network interfaces. If pressed again toggles
205 back to showing domains.
206 3 Toggle into showing block devices (virtual disks). If pressed
208 again toggles back to showing domains.
209 P Sort by %CPU.
211 M Sort by total memory. Note that this shows the total memory
213 allocated to the guest, not the memory being used.
214 T Sort by total time.
216 N Sort by domain ID.
218 F Select the sort field interactively (there are other sort fields
220 you can choose using this key).
221 W This creates or overwrites the init file with the current settings.
223 This key is disabled if --no-init-file was specified on the command
225 line or if overwrite-init-file false is given in the init file.
226
228 When virt-top starts up, it reads initial settings from the file
229 .virt-toprc in the user's home directory.
230 The name of this file may be overridden using the --init-file filename
232 command line option or may be disabled entirely using --no-init-file.
233 The init file has a simple format. Blank lines and comments beginning
235 with # are ignored. Everything else is a set of key value pairs,
236 described below.
237 display task|pcpu|block|net
239 Sets the major display mode to one of task (tasks, the default),
240 pcpu (physical CPUs), block (block devices), or net (network
241 interfaces).
242 delay secs
244 Sets the delay between display updates in seconds.
245 hist-cpu secs
247 Sets the historical CPU delay in seconds.
248 iterations n
250 Sets the number of iterations to run before we exit. Setting this
251 to -1 means to run continuously.
252 sort cpu|mem|time|id|name|...
254 Sets the sort order. The option names are the same as for the
255 command line -o option.
256 connect uri
258 Sets the default connection URI.
259 debug filename
261 Sets the default filename to use for debug and error messages.
262 csv filename
264 Enables CSV output to the named file.
265 csv-cpu true|false
267 Enable or disable domain CPU stats in CSV output.
268 csv-mem true|false
270 Enable or disable domain memory stats in CSV output.
271 csv-block true|false
273 Enable or disable domain block device stats in CSV output.
274 csv-net true|false
276 Enable or disable domain network interface stats in CSV output.
277 batch true|false
279 Sets batch mode.
280 secure true|false
282 Sets secure mode.
283 script true|false
285 Sets script mode.
286 stream true|false
288 Sets stream mode.
289 block-in-bytes true|false
291 Show block device statistics in bytes.
292 end-time time
294 Set the time at which the program exits. See above for the time
295 formats supported.
296 overwrite-init-file false
298 If set to false then the W key will not overwrite the init file.
299 Note that in the current implementation, options specified in the init
301 file override options specified on the command line. This is a bug and
302 this behaviour may change in the future.
303
305 %CPU
306 Percentage of CPU used. As with top(1), 100% means that all
307 physical CPUs are being fully used.
308 DEVICE
310 The block device name.
311 DOMAIN
313 NAME
314 The name of the libvirt domain.
315 ID The libvirt domain ID.
317 INTERFACE
319 The network interface name.
320 %MEM
322 The percentage of host memory assigned to the guest.
323 PHYCPU
325 The physical CPU.
326 RDBY
328 Disk bytes read since last displayed.
329 RDRQ
331 Disk read requests since last displayed.
332 RXBY
334 Network bytes received since last displayed.
335 RXPK
337 Network packets received since last displayed.
338 S The state of the domain, one of:
340 ? Unknown.
342 R Running.
344 S Blocked.
346 P Paused.
348 D
350 O Shutdown.
351 X Crashed.
353 M Suspended by guest power management.
355 TIME
357 Total CPU time used.
358 TXBY
360 Network bytes transmitted since last displayed.
361 TXPK
363 Network packets transmitted since last displayed.
364 WRBY
366 Disk bytes written since last displayed.
367 WRRQ
369 Disk write requests since last displayed.
370
372 Block I/O statistics
373 This I/O value is the amount of I/O since the previous iteration of
374 virt-top. To calculate speed of I/O, you should divide the number by
375 delay secs.
376 NETWORK RX BYTES AND PACKETS
378 Libvirt/virt-top has no way to know that a packet transmitted to a
379 guest was received (eg. if the guest is not listening). In the network
380 RX stats, virt-top reports the packets transmitted to the guest, on the
381 basis that the guest might receive them.
382 In particular this includes broadcast packets. Because of the way that
384 Linux bridges work, if the guest is connected to a bridge, it will
385 probably see a steady "background noise" of RX packets even when the
386 network interface is idle or down. These are caused by STP packets
387 generated by the bridge.
388 DEBUGGING LIBVIRT ISSUES
390 virt-top tries to turn libvirt errors into informative messages.
391 However if libvirt initialization fails then this is not possible.
392 Instead you will get an obscure error like:
393 libvir: error : Unknown failure
395 Fatal error: exception Libvirt.Virterror(...)
396 To see the cause of libvirt errors in more detail, enable libvirt
398 debugging by setting this environment variable:
399 export LIBVIRT_DEBUG=1
401
403 top(1), virsh(1), <http://www.libvirt.org/ocaml/>,
404 <http://www.libvirt.org/>, <http://people.redhat.com/~rjones/>,
405 <http://caml.inria.fr/>
406
408 Richard W.M. Jones <rjones @ redhat . com>
409
411 (C) Copyright 2007-2012 Red Hat Inc., Richard W.M. Jones
412 http://libvirt.org/
413 This program is free software; you can redistribute it and/or modify it
415 under the terms of the GNU General Public License as published by the
416 Free Software Foundation; either version 2 of the License, or (at your
417 option) any later version.
418 This program is distributed in the hope that it will be useful, but
420 WITHOUT ANY WARRANTY; without even the implied warranty of
421 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
422 General Public License for more details.
423 You should have received a copy of the GNU General Public License along
425 with this program; if not, write to the Free Software Foundation, Inc.,
426 675 Mass Ave, Cambridge, MA 02139, USA.
427
429 Bugs can be viewed on the Red Hat Bugzilla page:
430 <https://bugzilla.redhat.com/>.
431 If you find a bug in virt-top, please follow these steps to report it:
433 1. Check for existing bug reports
435 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
436 Someone may already have reported the same bug, and they may even
437 have fixed it.
438 2. Capture debug and error messages
440 Run
441 virt-top --debug virt-top.log
443 and keep virt-top.log. It contains error messages which you should
445 submit with your bug report.
446 3. Get version of virt-top and version of libvirt.
448 Use:
449 virt-top --version
451 If you can get the precise version of libvirt you are using then
453 that too is helpful.
454 4. Submit a bug report.
456 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
457 describe the problem in as much detail as possible.
458 Remember to include the version numbers (step 3) and the debug
460 messages file (step 2).
461 5. Assign the bug to rjones @ redhat.com
463 Assign or reassign the bug to rjones @ redhat.com (without the
464 spaces). You can also send me an email with the bug number if you
465 want a faster response.
466virt-top-1.1.1 2023-07-22 VIRT-TOP(1)