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           To save space you can compress your CSV files (if your shell
95           supports this feature, eg. bash):
96
97            virt-top --csv >(gzip -9 > output.csv.gz)
98
99           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
103            virt-top --csv >(split -d -l 1000 - output.csv.)
104
105       --no-csv-cpu
106           Disable domain CPU stats in CSV output.
107
108       --no-csv-mem
109           Disable domain memory stats in CSV output.
110
111       --no-csv-block
112           Disable domain block device stats in CSV output.
113
114       --no-csv-net
115           Disable domain network interface stats in CSV output.
116
117       --debug filename
118           Send debug and error messages to filename.  To send error messages
119           to syslog you can do:
120
121            virt-top --debug >(logger -t virt-top)
122
123           See also REPORTING BUGS below.
124
125       --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
129       --no-init-file
130           Do not read any init file.
131
132       --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
136       --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
140       --block-in-bytes
141           Show I/O statistics in Bytes. Default is shown in the number of
142           Requests.
143
144       --end-time time
145           The program will exit at the time given.
146
147           The time may be given in one of the following formats:
148
149           YYYY-MM-DD HH:MM:SS
150               End time is the date and time given.
151
152           HH:MM:SS
153               End time is the time given, today.
154
155           +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
159           +secs
160               End time is secs seconds in the future.
161
162           For example to run the program for 3 minutes you could do:
163
164            virt-top --end-time +00:03:00
165
166           or:
167
168            virt-top --end-time +180
169
170           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
174       --help
175           Display usage summary.
176
177       --version
178           Display version number and exit.
179

KEYS

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

INIT FILE

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

COLUMN HEADINGS

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

NOTES

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
377   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
383       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
389   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
394        libvir: error : Unknown failure
395        Fatal error: exception Libvirt.Virterror(...)
396
397       To see the cause of libvirt errors in more detail, enable libvirt
398       debugging by setting this environment variable:
399
400        export LIBVIRT_DEBUG=1
401

SEE ALSO

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

AUTHORS

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
414       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
419       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
424       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

REPORTING BUGS

429       Bugs can be viewed on the Red Hat Bugzilla page:
430       <https://bugzilla.redhat.com/>.
431
432       If you find a bug in virt-top, please follow these steps to report it:
433
434       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
439       2. Capture debug and error messages
440           Run
441
442            virt-top --debug virt-top.log
443
444           and keep virt-top.log.  It contains error messages which you should
445           submit with your bug report.
446
447       3. Get version of virt-top and version of libvirt.
448           Use:
449
450            virt-top --version
451
452           If you can get the precise version of libvirt you are using then
453           that too is helpful.
454
455       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
459           Remember to include the version numbers (step 3) and the debug
460           messages file (step 2).
461
462       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.
466
467
468
469virt-top-1.1.1                    2023-07-22                       VIRT-TOP(1)
Impressum