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 --no-csv-cpu
110 Disable domain CPU stats in CSV output.
111 --no-csv-mem
113 Disable domain memory stats in CSV output.
114 --no-csv-block
116 Disable domain block device stats in CSV output.
117 --no-csv-net
119 Disable domain network interface stats in CSV output.
120 --debug filename
122 Send debug and error messages to filename. To send error messages
123 to syslog you can do:
124 virt-top --debug >(logger -t virt-top)
126 See also REPORTING BUGS below.
128 --init-file filename
130 Read filename as the init file instead of the default which is
131 $HOME/.virt-toprc. See also INIT FILE below.
132 --no-init-file
134 Do not read any init file.
135 --script
137 Script mode. There will be no user interface. This is most useful
138 when used together with the --csv and -n options.
139 --stream
141 Stream mode. All output is sent to stdout. This can be used from
142 shell scripts etc. There is no user interface.
143 --block-in-bytes
145 Show I/O statistics in Bytes. Default is shown in the number of
146 Requests.
147 --end-time time
149 The program will exit at the time given.
150 The time may be given in one of the following formats:
152 YYYY-MM-DD HH:MM:SS
154 End time is the date and time given.
155 HH:MM:SS
157 End time is the time given, today.
158 +HH:MM:SS
160 End time is HH hours, MM minutes, SS seconds in the future
161 (counted from the moment that program starts).
162 +secs
164 End time is secs seconds in the future.
165 For example to run the program for 3 minutes you could do:
167 virt-top --end-time +00:03:00
169 or:
171 virt-top --end-time +180
173 Not every version of virt-top supports this option - it depends how
175 the program was compiled (see README file in the source
176 distribution for details).
177 --help
179 Display usage summary.
180 --version
182 Display version number and exit.
183
185 Note that keys are case sensitive. For example use upper-case P (shift
186 P) to sort by %CPU. ^ before a key means a Ctrl key, so ^L is Ctrl L.
187 space or ^L
189 Updates the display.
190 q Quits the program.
192 h Displays help.
194 s or d
196 Change the delay between screen updates.
197 B Toggle Block I/O statistics so they are shown in either bytes or
199 requests.
200 0 (number 0)
202 Show the normal list of domains display.
203 1 (number 1)
205 Toggle into showing physical CPUs. If pressed again toggles back
206 to showing domains (the normal display).
207 2 Toggle into showing network interfaces. If pressed again toggles
209 back to showing domains.
210 3 Toggle into showing block devices (virtual disks). If pressed
212 again toggles back to showing domains.
213 P Sort by %CPU.
215 M Sort by total memory. Note that this shows the total memory
217 allocated to the guest, not the memory being used.
218 T Sort by total time.
220 N Sort by domain ID.
222 F Select the sort field interactively (there are other sort fields
224 you can choose using this key).
225 W This creates or overwrites the init file with the current settings.
227 This key is disabled if --no-init-file was specified on the command
229 line or if overwrite-init-file false is given in the init file.
230
232 When virt-top starts up, it reads initial settings from the file
233 .virt-toprc in the user's home directory.
234 The name of this file may be overridden using the --init-file filename
236 command line option or may be disabled entirely using --no-init-file.
237 The init file has a simple format. Blank lines and comments beginning
239 with # are ignored. Everything else is a set of key value pairs,
240 described below.
241 display task|pcpu|block|net
243 Sets the major display mode to one of task (tasks, the default),
244 pcpu (physical CPUs), block (block devices), or net (network
245 interfaces).
246 delay secs
248 Sets the delay between display updates in seconds.
249 hist-cpu secs
251 Sets the historical CPU delay in seconds.
252 iterations n
254 Sets the number of iterations to run before we exit. Setting this
255 to -1 means to run continuously.
256 sort cpu|mem|time|id|name|...
258 Sets the sort order. The option names are the same as for the
259 command line -o option.
260 connect uri
262 Sets the default connection URI.
263 debug filename
265 Sets the default filename to use for debug and error messages.
266 csv filename
268 Enables CSV output to the named file.
269 csv-cpu true|false
271 Enable or disable domain CPU stats in CSV output.
272 csv-mem true|false
274 Enable or disable domain memory stats in CSV output.
275 csv-block true|false
277 Enable or disable domain block device stats in CSV output.
278 csv-net true|false
280 Enable or disable domain network interface stats in CSV output.
281 batch true|false
283 Sets batch mode.
284 secure true|false
286 Sets secure mode.
287 script true|false
289 Sets script mode.
290 stream true|false
292 Sets stream mode.
293 block-in-bytes true|false
295 Show block device statistics in bytes.
296 end-time time
298 Set the time at which the program exits. See above for the time
299 formats supported.
300 overwrite-init-file false
302 If set to false then the W key will not overwrite the init file.
303 Note that in the current implementation, options specified in the init
305 file override options specified on the command line. This is a bug and
306 this behaviour may change in the future.
307
309 %CPU
310 Percentage of CPU used. As with top(1), 100% means that all
311 physical CPUs are being fully used.
312 DEVICE
314 The block device name.
315 DOMAIN
317 NAME
318 The name of the libvirt domain.
319 ID The libvirt domain ID.
321 INTERFACE
323 The network interface name.
324 %MEM
326 The percentage of host memory assigned to the guest.
327 PHYCPU
329 The physical CPU.
330 RDBY
332 Disk bytes read since last displayed.
333 RDRQ
335 Disk read requests since last displayed.
336 RXBY
338 Network bytes received since last displayed.
339 RXPK
341 Network packets received since last displayed.
342 S The state of the domain, one of:
344 ? Unknown.
346 R Running.
348 S Blocked.
350 P Paused.
352 D
354 O Shutdown.
355 X Crashed.
357 M Suspended by guest power management.
359 TIME
361 Total CPU time used.
362 TXBY
364 Network bytes transmitted since last displayed.
365 TXPK
367 Network packets transmitted since last displayed.
368 WRBY
370 Disk bytes written since last displayed.
371 WRRQ
373 Disk write requests since last displayed.
374
376 Block I/O statistics
377 This I/O value is the amount of I/O since the previous iteration of
378 virt-top. To calculate speed of I/O, you should divide the number by
379 delay secs.
380 NETWORK RX BYTES AND PACKETS
382 Libvirt/virt-top has no way to know that a packet transmitted to a
383 guest was received (eg. if the guest is not listening). In the network
384 RX stats, virt-top reports the packets transmitted to the guest, on the
385 basis that the guest might receive them.
386 In particular this includes broadcast packets. Because of the way that
388 Linux bridges work, if the guest is connected to a bridge, it will
389 probably see a steady "background noise" of RX packets even when the
390 network interface is idle or down. These are caused by STP packets
391 generated by the bridge.
392 DEBUGGING LIBVIRT ISSUES
394 virt-top tries to turn libvirt errors into informative messages.
395 However if libvirt initialization fails then this is not possible.
396 Instead you will get an obscure error like:
397 libvir: error : Unknown failure
399 Fatal error: exception Libvirt.Virterror(...)
400 To see the cause of libvirt errors in more detail, enable libvirt
402 debugging by setting this environment variable:
403 export LIBVIRT_DEBUG=1
405
407 top(1), virsh(1), <http://www.libvirt.org/ocaml/>,
408 <http://www.libvirt.org/>, <http://people.redhat.com/~rjones/>,
409 <http://caml.inria.fr/>
410
412 Richard W.M. Jones <rjones @ redhat . com>
413
415 (C) Copyright 2007-2012 Red Hat Inc., Richard W.M. Jones
416 http://libvirt.org/
417 This program is free software; you can redistribute it and/or modify it
419 under the terms of the GNU General Public License as published by the
420 Free Software Foundation; either version 2 of the License, or (at your
421 option) any later version.
422 This program is distributed in the hope that it will be useful, but
424 WITHOUT ANY WARRANTY; without even the implied warranty of
425 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
426 General Public License for more details.
427 You should have received a copy of the GNU General Public License along
429 with this program; if not, write to the Free Software Foundation, Inc.,
430 675 Mass Ave, Cambridge, MA 02139, USA.
431
433 Bugs can be viewed on the Red Hat Bugzilla page:
434 <https://bugzilla.redhat.com/>.
435 If you find a bug in virt-top, please follow these steps to report it:
437 1. Check for existing bug reports
439 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
440 Someone may already have reported the same bug, and they may even
441 have fixed it.
442 2. Capture debug and error messages
444 Run
445 virt-top --debug virt-top.log
447 and keep virt-top.log. It contains error messages which you should
449 submit with your bug report.
450 3. Get version of virt-top and version of libvirt.
452 Use:
453 virt-top --version
455 If you can get the precise version of libvirt you are using then
457 that too is helpful.
458 4. Submit a bug report.
460 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
461 describe the problem in as much detail as possible.
462 Remember to include the version numbers (step 3) and the debug
464 messages file (step 2).
465 5. Assign the bug to rjones @ redhat.com
467 Assign or reassign the bug to rjones @ redhat.com (without the
468 spaces). You can also send me an email with the bug number if you
469 want a faster response.
470virt-top-1.0.9 2021-07-23 VIRT-TOP(1)