GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

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

SUMMARY

       virt-top [-options]

DESCRIPTION

       virt-top is a top(1)-like utility for showing stats of virtualized
       domains.  Many keys and command line options are the same as for
       ordinary top.

       It uses libvirt so it is capable of showing stats across a variety of
       different virtualization systems.

OPTIONS

       -1  Display physical CPUs by default (instead of domains).  When virt-
           top is running, use the 1 key to toggle between physical CPUs and
           domains display.

       -2  Display network interfaces by default (instead of domains).  When
           virt-top is running, use the 2 key to toggle between network
           interfaces and domains display.

       -3  Display block devices (virtual disks) by default (instead of
           domains).  When virt-top is running, use the 3 key to toggle
           between block devices and domains display.

       -b  Batch mode.  In this mode keypresses are ignored.

       -c uri or --connect uri
           Connect to the libvirt URI given.

           To connect to QEMU/KVM you would normally do -c qemu:///system

           To connect to Xen on the same host, do -c xen:///

           To connect to libvirtd on a remote machine you would normally do -c
           qemu://host/system

           If this option is not given then virt-top connects by default to
           whatever is the default hypervisor for libvirt, although this can
           be overridden by setting environment variables.

           See the libvirt documentation at <http://libvirt.org/uri.php> for
           further information.

       -d delay
           Set the delay between screen updates in seconds.  The default is
           3.0 seconds.  You can change this while virt-top is running by
           pressing either s or d key.

       -n iterations
           Set the number of iterations to run.  The default is to run
           continuously.

       -o sort
           Set the sort order to one of: cpu (sort by %CPU used), mem (sort by
           total memory), time (sort by total time), id (sort by domain ID),
           name (sort by domain name), netrx (sort by network received bytes),
           nettx (sort by network transmitted bytes), blockrdrq (sort by block
           device [disk] read requests), blockwrrq (sort by block device
           [disk] write requests).

           While virt-top is running you can change the sort order using keys
           P (cpu), M (memory), T (total time), N (domain ID), F
           (interactively select the sort field).

       -s  Secure mode.  Currently this does nothing.

       --hist-cpu secs
           Set the time in seconds between updates of the historical %CPU at
           the top right of the display.

       --csv file.csv
           Write the statistics to file file.csv.  First a header is written
           showing the statistics being recorded in each column, then one line
           is written for each screen update.  The CSV file can be loaded
           directly by most spreadsheet programs.

           Currently the statistics which this records vary between releases
           of virt-top (but the column headers will stay the same, so you can
           use those to process the CSV file).

           Not every version of virt-top supports CSV output - it depends how
           the program was compiled (see README file in the source
           distribution for details).

           To save space you can compress your CSV files (if your shell
           supports this feature, eg. bash):

            virt-top --csv >(gzip -9 > output.csv.gz)

           You can use a similar trick to split the CSV file up.  In this
           example the CSV file is split every 1000 lines into files called
           output.csv.00, output.csv.01 etc.

            virt-top --csv >(split -d -l 1000 - output.csv.)

       --no-csv-cpu
           Disable domain CPU stats in CSV output.

       --no-csv-mem
           Disable domain memory stats in CSV output.

       --no-csv-block
           Disable domain block device stats in CSV output.

       --no-csv-net
           Disable domain network interface stats in CSV output.

       --debug filename
           Send debug and error messages to filename.  To send error messages
           to syslog you can do:

            virt-top --debug >(logger -t virt-top)

           See also REPORTING BUGS below.

       --init-file filename
           Read filename as the init file instead of the default which is
           $HOME/.virt-toprc.  See also INIT FILE below.

       --no-init-file
           Do not read any init file.

       --script
           Script mode.  There will be no user interface.  This is most useful
           when used together with the --csv and -n options.

       --stream
           Stream mode.  All output is sent to stdout.  This can be used from
           shell scripts etc.  There is no user interface.

       --block-in-bytes
           Show I/O statistics in Bytes. Default is shown in the number of
           Requests.

       --end-time time
           The program will exit at the time given.

           The time may be given in one of the following formats:

           YYYY-MM-DD HH:MM:SS
               End time is the date and time given.

           HH:MM:SS
               End time is the time given, today.

           +HH:MM:SS
               End time is HH hours, MM minutes, SS seconds in the future
               (counted from the moment that program starts).

           +secs
               End time is secs seconds in the future.

           For example to run the program for 3 minutes you could do:

            virt-top --end-time +00:03:00

           or:

            virt-top --end-time +180

           Not every version of virt-top supports this option - it depends how
           the program was compiled (see README file in the source
           distribution for details).

       --help
           Display usage summary.

       --version
           Display version number and exit.

KEYS

       Note that keys are case sensitive.  For example use upper-case P (shift
       P) to sort by %CPU.  ^ before a key means a Ctrl key, so ^L is Ctrl L.

       space or ^L
           Updates the display.

       q   Quits the program.

       h   Displays help.

       s or d
           Change the delay between screen updates.

       B   Toggle Block I/O statistics so they are shown in either bytes or
           requests.

       0 (number 0)
           Show the normal list of domains display.

       1 (number 1)
           Toggle into showing physical CPUs.  If pressed again toggles back
           to showing domains (the normal display).

       2   Toggle into showing network interfaces.  If pressed again toggles
           back to showing domains.

       3   Toggle into showing block devices (virtual disks).  If pressed
           again toggles back to showing domains.

       P   Sort by %CPU.

       M   Sort by total memory.  Note that this shows the total memory
           allocated to the guest, not the memory being used.

       T   Sort by total time.

       N   Sort by domain ID.

       F   Select the sort field interactively (there are other sort fields
           you can choose using this key).

       W   This creates or overwrites the init file with the current settings.

           This key is disabled if --no-init-file was specified on the command
           line or if overwrite-init-file false is given in the init file.

INIT FILE

       When virt-top starts up, it reads initial settings from the file
       .virt-toprc in the user's home directory.

       The name of this file may be overridden using the --init-file filename
       command line option or may be disabled entirely using --no-init-file.

       The init file has a simple format.  Blank lines and comments beginning
       with # are ignored.  Everything else is a set of key value pairs,
       described below.

       display task|pcpu|block|net
           Sets the major display mode to one of task (tasks, the default),
           pcpu (physical CPUs), block (block devices), or net (network
           interfaces).

       delay secs
           Sets the delay between display updates in seconds.

       hist-cpu secs
           Sets the historical CPU delay in seconds.

       iterations n
           Sets the number of iterations to run before we exit.  Setting this
           to -1 means to run continuously.

       sort cpu|mem|time|id|name|...
           Sets the sort order.  The option names are the same as for the
           command line -o option.

       connect uri
           Sets the default connection URI.

       debug filename
           Sets the default filename to use for debug and error messages.

       csv filename
           Enables CSV output to the named file.

       csv-cpu true|false
           Enable or disable domain CPU stats in CSV output.

       csv-mem true|false
           Enable or disable domain memory stats in CSV output.

       csv-block true|false
           Enable or disable domain block device stats in CSV output.

       csv-net true|false
           Enable or disable domain network interface stats in CSV output.

       batch true|false
           Sets batch mode.

       secure true|false
           Sets secure mode.

       script true|false
           Sets script mode.

       stream true|false
           Sets stream mode.

       block-in-bytes true|false
           Show block device statistics in bytes.

       end-time time
           Set the time at which the program exits.  See above for the time
           formats supported.

       overwrite-init-file false
           If set to false then the W key will not overwrite the init file.

       Note that in the current implementation, options specified in the init
       file override options specified on the command line.  This is a bug and
       this behaviour may change in the future.

NOTES

   Block I/O statistics
       This I/O value is the amount of I/O since the previous iteration of
       virt-top. To calculate speed of I/O, you should divide the number by
       delay secs.

   NETWORK RX BYTES AND PACKETS
       Libvirt/virt-top has no way to know that a packet transmitted to a
       guest was received (eg. if the guest is not listening).  In the network
       RX stats, virt-top reports the packets transmitted to the guest, on the
       basis that the guest might receive them.

       In particular this includes broadcast packets.  Because of the way that
       Linux bridges work, if the guest is connected to a bridge, it will
       probably see a steady "background noise" of RX packets even when the
       network interface is idle or down.  These are caused by STP packets
       generated by the bridge.

   DEBUGGING LIBVIRT ISSUES
       virt-top tries to turn libvirt errors into informative messages.
       However if libvirt initialization fails then this is not possible.
       Instead you will get an obscure error like:

        libvir: error : Unknown failure
        Fatal error: exception Libvirt.Virterror(...)

       To see the cause of libvirt errors in more detail, enable libvirt
       debugging by setting this environment variable:

        export LIBVIRT_DEBUG=1

SEE ALSO

       top(1), virsh(1), <http://www.libvirt.org/ocaml/>,
       <http://www.libvirt.org/>, <http://people.redhat.com/~rjones/>,
       <http://caml.inria.fr/>

AUTHORS

       Richard W.M. Jones <rjones @ redhat . com>

COPYRIGHT

       (C) Copyright 2007-2011 Red Hat Inc., Richard W.M. Jones
       http://libvirt.org/

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       675 Mass Ave, Cambridge, MA 02139, USA.

REPORTING BUGS

       Bugs can be viewed on the Red Hat Bugzilla page:
       <https://bugzilla.redhat.com/>.

       If you find a bug in virt-top, please follow these steps to report it:

       1. Check for existing bug reports
           Go to <https://bugzilla.redhat.com/> and search for similar bugs.
           Someone may already have reported the same bug, and they may even
           have fixed it.

       2. Capture debug and error messages
           Run

            virt-top --debug virt-top.log

           and keep virt-top.log.  It contains error messages which you should
           submit with your bug report.

       3. Get version of virt-top and version of libvirt.
           Use:

            virt-top --version

           If you can get the precise version of libvirt you are using then
           that too is helpful.

       4. Submit a bug report.
           Go to <https://bugzilla.redhat.com/> and enter a new bug.  Please
           describe the problem in as much detail as possible.

           Remember to include the version numbers (step 3) and the debug
           messages file (step 2).

       5. Assign the bug to rjones @ redhat.com
           Assign or reassign the bug to rjones @ redhat.com (without the
           spaces).  You can also send me an email with the bug number if you
           want a faster response.



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.152 seconds. Last modified: November 04 2018 12:49:43.