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). When virt-
21 top is running, use the 1 key to toggle between physical CPUs and
22 domains display.
23 -2 Display network interfaces by default (instead of domains). When
25 virt-top is running, use the 2 key to toggle between network
26 interfaces and domains display.
27 -3 Display block devices (virtual disks) by default (instead of
29 domains). When virt-top is running, use the 3 key to toggle
30 between block devices and domains display.
31 -b Batch mode. In this mode keypresses are ignored.
33 -c uri or --connect uri
35 Connect to URI given. The default is to connect to the Xen
36 hypervisor.
37 To connect to QEMU/KVM you would normally do -c qemu:///system
39 To connect to libvirtd on a remote machine you would normally do -c
41 xen://host/
42 Full details on connection URIs is available at
44 <http://libvirt.org/uri.html>
45 -d delay
47 Set the delay between screen updates in seconds. The default is
48 3.0 seconds. You can change this while virt-top is running by
49 pressing either s or d key.
50 -n iterations
52 Set the number of iterations to run. The default is to run
53 continuously.
54 -o sort
56 Set the sort order to one of: cpu (sort by %CPU used), mem (sort by
57 memory used), time (sort by total time), id (sort by domain ID),
58 name (sort by domain name), netrx (sort by network received bytes),
59 nettx (sort by network transmitted bytes), blockrdrq (sort by block
60 device [disk] read requests), blockwrrq (sort by block device
61 [disk] write requests).
62 While virt-top is running you can change the sort order using keys
64 P (cpu), M (memory), T (total time), N (domain ID), F
65 (interactively select the sort field).
66 -s Secure mode. Currently this does nothing.
68 --hist-cpu secs
70 Set the time in seconds between updates of the historical %CPU at
71 the top right of the display.
72 --csv file.csv
74 Write the statistics to file file.csv. First a header is written
75 showing the statistics being recorded in each column, then one line
76 is written for each screen update. The CSV file can be loaded
77 directly by most spreadsheet programs.
78 Currently the statistics which this records vary between releases
80 of virt-top (but the column headers will stay the same, so you can
81 use those to process the CSV file).
82 Not every version of virt-top supports CSV output - it depends how
84 the program was compiled (see README file in the source
85 distribution for details).
86 To save space you can compress your CSV files (if your shell
88 supports this feature, eg. bash):
89 virt-top --csv >(gzip -9 > output.csv.gz)
91 You can use a similar trick to split the CSV file up. In this
93 example the CSV file is split every 1000 lines into files called
94 output.csv.00, output.csv.01 etc.
95 virt-top --csv >(split -d -l 1000 - output.csv.)
97 --no-csv-cpu
99 Disable domain CPU stats in CSV output.
100 --no-csv-block
102 Disable domain block device stats in CSV output.
103 --no-csv-net
105 Disable domain network interface stats in CSV output.
106 --debug filename
108 Send debug and error messages to filename. To send error messages
109 to syslog you can do:
110 virt-top --debug >(logger -t virt-top)
112 See also REPORTING BUGS below.
114 --init-file filename
116 Read filename as the init file instead of the default which is
117 $HOME/.virt-toprc. See also INIT FILE below.
118 --no-init-file
120 Do not read any init file.
121 --script
123 Script mode. There will be no user interface. This is most useful
124 when used together with the --csv and -n options.
125 --end-time time
127 The program will exit at the time given.
128 The time may be given in one of the following formats:
130 YYYY-MM-DD HH:MM:SS
132 End time is the date and time given.
133 HH:MM:SS
135 End time is the time given, today.
136 +HH:MM:SS
138 End time is HH hours, MM minutes, SS seconds in the future
139 (counted from the moment that program starts).
140 +secs
142 End time is secs seconds in the future.
143 For example to run the program for 3 minutes you could do:
145 virt-top --end-time +00:03:00
147 or:
149 virt-top --end-time +180
151 Not every version of virt-top supports this option - it depends how
153 the program was compiled (see README file in the source
154 distribution for details).
155 --help
157 Display usage summary.
158
160 Note that keys are case sensitive. For example use upper-case P (shift
161 P) to sort by %CPU. ^ before a key means a Ctrl key, so ^L is Ctrl L.
162 space or ^L
164 Updates the display.
165 q Quits the program.
167 h Displays help.
169 s or d
171 Change the delay between screen updates.
172 0 (number 0)
174 Show the normal list of domains display.
175 1 (number 1)
177 Toggle into showing physical CPUs. If pressed again toggles back
178 to showing domains (the normal display).
179 2 Toggle into showing network interfaces. If pressed again toggles
181 back to showing domains.
182 3 Toggle into showing block devices (virtual disks). If pressed
184 again toggles back to showing domains.
185 P Sort by %CPU.
187 M Sort by memory.
189 T Sort by total time.
191 N Sort by domain ID.
193 F Select the sort field interactively (there are other sort fields
195 you can choose using this key).
196 W This creates or overwrites the init file with the current settings.
198 This key is disabled if --no-init-file was specified on the command
200 line or if overwrite-init-file false is given in the init file.
201
203 When virt-top starts up, it reads initial settings from the file
204 .virt-toprc in the user's home directory.
205 The name of this file may be overridden using the --init-file filename
207 command line option or may be disabled entirely using --no-init-file.
208 The init file has a simple format. Blank lines and comments beginning
210 with # are ignored. Everything else is a set of key value pairs,
211 described below.
212 display task|pcpu|block|net
214 Sets the major display mode to one of task (tasks, the default),
215 pcpu (physical CPUs), block (block devices), or net (network
216 interfaces).
217 delay secs
219 Sets the delay between display updates in seconds.
220 hist-cpu secs
222 Sets the historical CPU delay in seconds.
223 iterations n
225 Sets the number of iterations to run before we exit. Setting this
226 to -1 means to run continuously.
227 sort cpu|mem|time|id|name|...
229 Sets the sort order. The option names are the same as for the
230 command line -o option.
231 connect uri
233 Sets the default connection URI.
234 debug filename
236 Sets the default filename to use for debug and error messages.
237 csv filename
239 Enables CSV output to the named file.
240 csv-cpu true|false
242 Enable or disable domain CPU stats in CSV output.
243 csv-block true|false
245 Enable or disable domain block device stats in CSV output.
246 csv-net true|false
248 Enable or disable domain network interface stats in CSV output.
249 batch true|false
251 Sets batch mode.
252 secure true|false
254 Sets secure mode.
255 script true|false
257 Sets script mode.
258 end-time time
260 Set the time at which the program exits. See above for the time
261 formats supported.
262 overwrite-init-file false
264 If set to false then the W key will not overwrite the init file.
265 Note that in the current implementation, options specified in the init
267 file override options specified on the command line. This is a bug and
268 this behaviour may change in the future.
269
271 top(1), virsh(1), xm(1), xentop(1), <http://www.libvirt.org/ocaml/>,
272 <http://www.libvirt.org/>, <http://et.redhat.com/~rjones/>,
273 <http://caml.inria.fr/>
274
276 Richard W.M. Jones <rjones @ redhat . com>
277
279 (C) Copyright 2007 Red Hat Inc., Richard W.M. Jones http://libvirt.org/
280 This program is free software; you can redistribute it and/or modify it
282 under the terms of the GNU General Public License as published by the
283 Free Software Foundation; either version 2 of the License, or (at your
284 option) any later version.
285 This program is distributed in the hope that it will be useful, but
287 WITHOUT ANY WARRANTY; without even the implied warranty of
288 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
289 General Public License for more details.
290 You should have received a copy of the GNU General Public License along
292 with this program; if not, write to the Free Software Foundation, Inc.,
293 675 Mass Ave, Cambridge, MA 02139, USA.
294
296 Bugs can be viewed on the Red Hat Bugzilla page:
297 <https://bugzilla.redhat.com/>.
298 If you find a bug in virt-top, please follow these steps to report it:
300 1. Check for existing bug reports
302 Go to <https://bugzilla.redhat.com/> and search for similar bugs.
303 Someone may already have reported the same bug, and they may even
304 have fixed it.
305 2. Capture debug and error messages
307 Run
308 virt-top --debug virt-top.log
310 and keep virt-top.log. It contains error messages which you should
312 submit with your bug report.
313 3. Get version of virt-top and version of libvirt.
315 In virt-top, press the h (help) key, and write down the version of
316 virt-top and the version of libvirt. They are shown in the first
317 line.
318 4. Submit a bug report.
320 Go to <https://bugzilla.redhat.com/> and enter a new bug. Please
321 describe the problem in as much detail as possible.
322 Remember to include the version numbers (step 3) and the debug
324 messages file (step 2).
325 5. Assign the bug to rjones @ redhat.com
327 Assign or reassign the bug to rjones @ redhat.com (without the
328 spaces). You can also send me an email with the bug number if you
329 want a faster response.
330virt-top-1.0.4 2009-10-05 VIRT-TOP(1)