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).

        Under each domain column, two numbers are shown. The first is the
        percentage of the physical CPU used by the domain and the hypervisor
        together. The second is the percentage used by just the domain.

        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.html> 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.

COLUMN HEADINGS
    %CPU
        Percentage of CPU used. As with top(1), 100% means that all physical
        CPUs are being fully used.

    DEVICE
        The block device name.

    DOMAIN
    NAME
        The name of the libvirt domain.

    ID  The libvirt domain ID.

    INTERFACE
        The network interface name.

    %MEM
        The percentage of host memory assigned to the guest.

    PHYCPU
        The physical CPU.

    RDBY
        Disk bytes read since last displayed.

    RDRQ
        Disk read requests since last displayed.

    RXBY
        Network bytes received since last displayed.

    RXPK
        Network packets received since last displayed.

    S   The state of the domain, one of:

        ?   Unknown.

        R   Running.

        S   Blocked.

        P   Paused.

        D
        O   Shutdown.

        X   Crashed.

    TIME
        Total CPU time used.

    TXBY
        Network bytes transmitted since last displayed.

    TXPK
        Network packets transmitted since last displayed.

    WRBY
        Disk bytes written since last displayed.

    WRRQ
        Disk write requests since last displayed.

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-2012 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.

