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           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
112            virt-top --csv data.csv
113            processcsv.py < data.csv
114
115           This creates or overwrites the following files in the current
116           directory:
117
118            global.csv
119            domain<NNN>.csv
120
121           "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
125       --no-csv-cpu
126           Disable domain CPU stats in CSV output.
127
128       --no-csv-mem
129           Disable domain memory stats in CSV output.
130
131       --no-csv-block
132           Disable domain block device stats in CSV output.
133
134       --no-csv-net
135           Disable domain network interface stats in CSV output.
136
137       --debug filename
138           Send debug and error messages to filename.  To send error messages
139           to syslog you can do:
140
141            virt-top --debug >(logger -t virt-top)
142
143           See also REPORTING BUGS below.
144
145       --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
149       --no-init-file
150           Do not read any init file.
151
152       --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
156       --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
160       --block-in-bytes
161           Show I/O statistics in Bytes. Default is shown in the number of
162           Requests.
163
164       --end-time time
165           The program will exit at the time given.
166
167           The time may be given in one of the following formats:
168
169           YYYY-MM-DD HH:MM:SS
170               End time is the date and time given.
171
172           HH:MM:SS
173               End time is the time given, today.
174
175           +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
179           +secs
180               End time is secs seconds in the future.
181
182           For example to run the program for 3 minutes you could do:
183
184            virt-top --end-time +00:03:00
185
186           or:
187
188            virt-top --end-time +180
189
190           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
194       --help
195           Display usage summary.
196
197       --version
198           Display version number and exit.
199

KEYS

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

INIT FILE

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

COLUMN HEADINGS

325       %CPU
326           Percentage of CPU used.  As with top(1), 100% means that all
327           physical CPUs are being fully used.
328
329       DEVICE
330           The block device name.
331
332       DOMAIN
333       NAME
334           The name of the libvirt domain.
335
336       ID  The libvirt domain ID.
337
338       INTERFACE
339           The network interface name.
340
341       %MEM
342           The percentage of host memory assigned to the guest.
343
344       PHYCPU
345           The physical CPU.
346
347       RDBY
348           Disk bytes read since last displayed.
349
350       RDRQ
351           Disk read requests since last displayed.
352
353       RXBY
354           Network bytes received since last displayed.
355
356       RXPK
357           Network packets received since last displayed.
358
359       S   The state of the domain, one of:
360
361           ?   Unknown.
362
363           R   Running.
364
365           S   Blocked.
366
367           P   Paused.
368
369           D
370           O   Shutdown.
371
372           X   Crashed.
373
374       TIME
375           Total CPU time used.
376
377       TXBY
378           Network bytes transmitted since last displayed.
379
380       TXPK
381           Network packets transmitted since last displayed.
382
383       WRBY
384           Disk bytes written since last displayed.
385
386       WRRQ
387           Disk write requests since last displayed.
388

NOTES

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
395   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
401       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
407   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
412        libvir: error : Unknown failure
413        Fatal error: exception Libvirt.Virterror(...)
414
415       To see the cause of libvirt errors in more detail, enable libvirt
416       debugging by setting this environment variable:
417
418        export LIBVIRT_DEBUG=1
419

SEE ALSO

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

AUTHORS

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
432       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
437       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
442       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

REPORTING BUGS

447       Bugs can be viewed on the Red Hat Bugzilla page:
448       <https://bugzilla.redhat.com/>.
449
450       If you find a bug in virt-top, please follow these steps to report it:
451
452       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
457       2. Capture debug and error messages
458           Run
459
460            virt-top --debug virt-top.log
461
462           and keep virt-top.log.  It contains error messages which you should
463           submit with your bug report.
464
465       3. Get version of virt-top and version of libvirt.
466           Use:
467
468            virt-top --version
469
470           If you can get the precise version of libvirt you are using then
471           that too is helpful.
472
473       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
477           Remember to include the version numbers (step 3) and the debug
478           messages file (step 2).
479
480       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.
484
485
486
487virt-top-1.0.8                    2019-05-17                       VIRT-TOP(1)
Impressum