1VIRT-TOP(1)                 Virtualization Support                 VIRT-TOP(1)
2
3
4

NAME

6       virt-top - 'top'-like utility for virtualization stats
7

SUMMARY

9       virt-top [-options]
10

DESCRIPTION

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
16       It uses libvirt so it is capable of showing stats across a variety of
17       different virtualization systems.
18

OPTIONS

20       -1  Display physical CPUs by default (instead of domains).
21
22           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
27           When virt-top is running, use the 1 key to toggle between physical
28           CPUs and domains display.
29
30       -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
34       -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
38       -b  Batch mode.  In this mode keypresses are ignored.
39
40       -c uri or --connect uri
41           Connect to the libvirt URI given.
42
43           To connect to QEMU/KVM you would normally do -c qemu:///system
44
45           To connect to Xen on the same host, do -c xen:///
46
47           To connect to libvirtd on a remote machine you would normally do -c
48           qemu://host/system
49
50           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
54           See the libvirt documentation at <http://libvirt.org/uri.html> for
55           further information.
56
57       -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
62       -n iterations
63           Set the number of iterations to run.  The default is to run
64           continuously.
65
66       -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
74           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
78       -s  Secure mode.  Currently this does nothing.
79
80       --hist-cpu secs
81           Set the time in seconds between updates of the historical %CPU at
82           the top right of the display.
83
84       --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
90           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
94           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
98           To save space you can compress your CSV files (if your shell
99           supports this feature, eg. bash):
100
101            virt-top --csv >(gzip -9 > output.csv.gz)
102
103           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
107            virt-top --csv >(split -d -l 1000 - output.csv.)
108
109       --no-csv-cpu
110           Disable domain CPU stats in CSV output.
111
112       --no-csv-mem
113           Disable domain memory stats in CSV output.
114
115       --no-csv-block
116           Disable domain block device stats in CSV output.
117
118       --no-csv-net
119           Disable domain network interface stats in CSV output.
120
121       --debug filename
122           Send debug and error messages to filename.  To send error messages
123           to syslog you can do:
124
125            virt-top --debug >(logger -t virt-top)
126
127           See also REPORTING BUGS below.
128
129       --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
133       --no-init-file
134           Do not read any init file.
135
136       --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
140       --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
144       --block-in-bytes
145           Show I/O statistics in Bytes. Default is shown in the number of
146           Requests.
147
148       --end-time time
149           The program will exit at the time given.
150
151           The time may be given in one of the following formats:
152
153           YYYY-MM-DD HH:MM:SS
154               End time is the date and time given.
155
156           HH:MM:SS
157               End time is the time given, today.
158
159           +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
163           +secs
164               End time is secs seconds in the future.
165
166           For example to run the program for 3 minutes you could do:
167
168            virt-top --end-time +00:03:00
169
170           or:
171
172            virt-top --end-time +180
173
174           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
178       --help
179           Display usage summary.
180
181       --version
182           Display version number and exit.
183

KEYS

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
188       space or ^L
189           Updates the display.
190
191       q   Quits the program.
192
193       h   Displays help.
194
195       s or d
196           Change the delay between screen updates.
197
198       B   Toggle Block I/O statistics so they are shown in either bytes or
199           requests.
200
201       0 (number 0)
202           Show the normal list of domains display.
203
204       1 (number 1)
205           Toggle into showing physical CPUs.  If pressed again toggles back
206           to showing domains (the normal display).
207
208       2   Toggle into showing network interfaces.  If pressed again toggles
209           back to showing domains.
210
211       3   Toggle into showing block devices (virtual disks).  If pressed
212           again toggles back to showing domains.
213
214       P   Sort by %CPU.
215
216       M   Sort by total memory.  Note that this shows the total memory
217           allocated to the guest, not the memory being used.
218
219       T   Sort by total time.
220
221       N   Sort by domain ID.
222
223       F   Select the sort field interactively (there are other sort fields
224           you can choose using this key).
225
226       W   This creates or overwrites the init file with the current settings.
227
228           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

INIT FILE

232       When virt-top starts up, it reads initial settings from the file
233       .virt-toprc in the user's home directory.
234
235       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
238       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
242       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
247       delay secs
248           Sets the delay between display updates in seconds.
249
250       hist-cpu secs
251           Sets the historical CPU delay in seconds.
252
253       iterations n
254           Sets the number of iterations to run before we exit.  Setting this
255           to -1 means to run continuously.
256
257       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
261       connect uri
262           Sets the default connection URI.
263
264       debug filename
265           Sets the default filename to use for debug and error messages.
266
267       csv filename
268           Enables CSV output to the named file.
269
270       csv-cpu true|false
271           Enable or disable domain CPU stats in CSV output.
272
273       csv-mem true|false
274           Enable or disable domain memory stats in CSV output.
275
276       csv-block true|false
277           Enable or disable domain block device stats in CSV output.
278
279       csv-net true|false
280           Enable or disable domain network interface stats in CSV output.
281
282       batch true|false
283           Sets batch mode.
284
285       secure true|false
286           Sets secure mode.
287
288       script true|false
289           Sets script mode.
290
291       stream true|false
292           Sets stream mode.
293
294       block-in-bytes true|false
295           Show block device statistics in bytes.
296
297       end-time time
298           Set the time at which the program exits.  See above for the time
299           formats supported.
300
301       overwrite-init-file false
302           If set to false then the W key will not overwrite the init file.
303
304       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

COLUMN HEADINGS

309       %CPU
310           Percentage of CPU used.  As with top(1), 100% means that all
311           physical CPUs are being fully used.
312
313       DEVICE
314           The block device name.
315
316       DOMAIN
317       NAME
318           The name of the libvirt domain.
319
320       ID  The libvirt domain ID.
321
322       INTERFACE
323           The network interface name.
324
325       %MEM
326           The percentage of host memory assigned to the guest.
327
328       PHYCPU
329           The physical CPU.
330
331       RDBY
332           Disk bytes read since last displayed.
333
334       RDRQ
335           Disk read requests since last displayed.
336
337       RXBY
338           Network bytes received since last displayed.
339
340       RXPK
341           Network packets received since last displayed.
342
343       S   The state of the domain, one of:
344
345           ?   Unknown.
346
347           R   Running.
348
349           S   Blocked.
350
351           P   Paused.
352
353           D
354           O   Shutdown.
355
356           X   Crashed.
357
358           M   Suspended by guest power management.
359
360       TIME
361           Total CPU time used.
362
363       TXBY
364           Network bytes transmitted since last displayed.
365
366       TXPK
367           Network packets transmitted since last displayed.
368
369       WRBY
370           Disk bytes written since last displayed.
371
372       WRRQ
373           Disk write requests since last displayed.
374

NOTES

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
381   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
387       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
393   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
398        libvir: error : Unknown failure
399        Fatal error: exception Libvirt.Virterror(...)
400
401       To see the cause of libvirt errors in more detail, enable libvirt
402       debugging by setting this environment variable:
403
404        export LIBVIRT_DEBUG=1
405

SEE ALSO

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

AUTHORS

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
418       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
423       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
428       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

REPORTING BUGS

433       Bugs can be viewed on the Red Hat Bugzilla page:
434       <https://bugzilla.redhat.com/>.
435
436       If you find a bug in virt-top, please follow these steps to report it:
437
438       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
443       2. Capture debug and error messages
444           Run
445
446            virt-top --debug virt-top.log
447
448           and keep virt-top.log.  It contains error messages which you should
449           submit with your bug report.
450
451       3. Get version of virt-top and version of libvirt.
452           Use:
453
454            virt-top --version
455
456           If you can get the precise version of libvirt you are using then
457           that too is helpful.
458
459       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
463           Remember to include the version numbers (step 3) and the debug
464           messages file (step 2).
465
466       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.
470
471
472
473virt-top-1.0.9                    2021-07-23                       VIRT-TOP(1)
Impressum