pcp-dstat(1) — Linux manual page


PCP-DSTAT(1)             General Commands Manual            PCP-DSTAT(1)

NAME         top

       pcp-dstat - versatile tool for generating system resource

SYNOPSIS         top

       pcp [pcp options] dstat [-acdfghilmnpqrstvVy?]  [-C cpus] [-D
       disks] [-L DM devices] [-M MD devices] [-P partitions] [-I
       interrupts] [-N interfaces] [-o output-file] [-S swap-devices]
       [--bits] [--bw] [--color] [--float] [--integer] [--nocolor]
       [--noheaders] [--noupdate] [--list] [--pidfile pid-file]
       [--plugin] [--all-plugins] [delay [count]]

DESCRIPTION         top

       pcp-dstat is a general performance analysis tool allowing you to
       view multiple system resources instantly, for example you can
       compare disk usage in combination with interrupts from a disk
       controller, or compare the network bandwidth numbers directly
       with the disk throughput (in the same interval).

       It also cleverly gives you the most detailed information in
       columns and clearly indicates in what magnitude and unit the
       output is being displayed.  Less confusion, fewer mistakes, more

       The delay is the delay in seconds between each update, and the
       count is the number of updates to display before exiting.  The
       default delay is 1 second and count is unspecified (run until
       interrupted or end of archive is reached).

       This latest generation of Dstat, pcp-dstat, allows for analysis
       of historical performance data (in the PCP archive format created
       by pmlogger(1)), as well as distributed systems analysis of live
       performance data from remote hosts running the pmcd(1) process.

       The original Dstat notion of ``plugins'' is replaced by use of
       named metrics in a Performance Metric Name Space (PMNS(5))
       supplied by Performance Metric Domain Agents (PMDAs).  Metrics
       and other formatting information is now specified as plugin
       configuration files in pcp-dstat(5) format.  This new style of
       plugin is either built-in (time-related reporting only), or
       sourced from the system-wide location ($PCP_SYSCONF_DIR/dstat)
       and/or sourced from an individual users set of personal plugins

       The list of all available plugins can be seen using the --list
       dstat command line option.

OPTIONS         top

       When invoked via the pcp(1) command, the -h/--host, -a/--archive,
       -O/--origin, -Z/--timezone and several other pcp options become
       indirectly available; refer to PCPIntro(1) for a complete
       description of these options.

       The additional command line options available for pcp-dstat are:

       --list list all available plugin names

            enable any plugin by name

       -a, --all
            equals -cdngy (default plugin set)

       -c, --cpu
            enable CPU stats (system, user, idle, wait); for more CPU
            related stats also see --cpu-adv and --cpu-use

       -C 0,3,total
            include CPU0, CPU3 and total (when using -c/--cpu); use all
            to show all CPUs

       -d, --disk
            enable disk stats (read, write); for more disk related stats
            look into the other --disk plugins

       -D total,hda
            include total and hda (when using -d/--disk or --disk-tps

       --dm, --device-mapper
            enable device mapper stats (read, write); for more device-
            mapper related stats look into the other --dm plugins

       --L total,root,home
            include total, root and home (when using --dm/--device-
            mapper or --dm-tps plugin)

       --md, --multi-device
            enable multi-device driver stats (read, write); for more
            multi-device driver related stats look into the other --md

       --M total,md-0
            include total and md-0 (when using --md/--multi-device or
            --md-tps plugin)

       --part, --partition
            enable disk partition stats (read, write); for more
            partition related stats look into the other --part plugins

       --P total,sda2
            include total and sda2 (when using --part/--partition or
            --part-tps plugin)

       -g, --page
            enable page stats (page in, page out)

       -i, --int
            enable interrupt stats

       -I 5,10
            include interrupt 5 and 10 (when using -i/--int)

       -l, --load
            enable load average stats (1 min, 5 mins, 15 mins)

       -m, --mem
            enable memory stats (used, buffers, cache, free); for more
            memory related stats also try --mem-adv and --swap

       -n, --net
            enable network stats (receive, send)

       -N eth1,total
            include eth1 and total (when using -n/--net)

            show the number of packets received and transmitted

       -p, --proc
            enable process stats (runnable, uninterruptible, new)

            show total number of processes

       -r, --io
            enable I/O request stats (read, write requests)

       -s, --swap
            enable swap stats (used, free)

       -S swap1,total
            include swap1 and total (when using -s/--swap)

       --snooze show time spent between updates in seconds

       -t, --time
              enable time/date output (try --time-adv for millisecond

       -T, --epoch
              enable time counter (seconds since epoch, or millisecond
              precision from the --epoch-adv plugin)

       -y, --sys
              enable system stats (interrupts, context switches)

       --aio  enable aio stats (asynchronous I/O)

              enable advanced CPU stats

              enable only CPU usage stats

              average queue length of the requests that were issued to
              the device

              average size (in sectors) of the requests that were issued
              to the device

              average service time (in milliseconds) for I/O requests
              that were issued to the device

              number of transfers per second that were issued to the

              percentage of CPU time during which I/O requests were
              issued to the device (bandwidth utilization for the

              average time (in milliseconds) for I/O requests issued to
              the device to be served

       --fs, --filesystem
              enable filesystem stats (open files, inodes)

              per filesystem used and available space

       --ipc  enable ipc stats (message queue, semaphores, shared

       --lock enable file lock stats (posix, flock, read, write)

              enable advanced memory stats

       --raw  enable raw stats (raw sockets)

              enable socket stats (total, tcp, udp, raw, ip-fragments)

       --tcp  enable tcp stats (listen, established, syn, time_wait,

       --udp  enable udp stats (listen, active)

       --unix enable unix stats (datagram, stream, listen, active)

       --utmp shows login information from utmp(5)

       --vm   enable virtual memory stats (hard pagefaults, soft
              pagefaults, allocated, free)

              enable advance virtual memory stats (steal, scanK, scanD,
              pgoru, astll)

       --nfs3 show NFS v3 client operations

              show extended NFS v3 client operations

              show NFS v3 server operations

              show extended NFS v3 server operations

              show extended NFS v4 server operations

              show NFS v4 stats

       --rpc  show remote procedure call (RPC) client calls stats

       --rpcd show remote procedure call (RPC) server calls stats

       -f, --full
              expand -C, -D, -I, -N and -S discovery lists

       -v, --vmstat
              equals -pmgdsc -D total

       --bits force bits for values expressed in bytes

              force float values on screen (mutually exclusive with

              force integer values on screen (mutually exclusive with

       --bw, --blackonwhite
              change colors for white background terminal

              disable colors

              disable repetitive headers

              disable intermediate updates when delay greater than 1.

       -o file, --output=file
              write CSV (Comma-Separated Value) format output to a file.

       -p file, --pidfile=file
              write the process identifier to a given file.


       Some pcp-dstat configuration files require the installation of
       optional Performance Metric Domain Agents, above and beyond the
       default installed set.

            GPFS read/write I/O (needs the GPFS PMDA)

            GPFS filesystem operations (needs the GPFS PMDA)

            show innodb buffer stats (needs the MySQL PMDA)

            show innodb I/O stats (needs the MySQL PMDA)

            show innodb operations counters (needs the MySQL PMDA)

            show lustre I/O throughput (needs the Lustre PMDA)

            show the number of hits and misses from memcache

            show the MySQL5 command stats (needs the MySQL PMDA)

            show the MySQL5 connection stats (needs the MySQL PMDA)

            show the MySQL5 innodb stats (needs the MySQL PMDA)

            show the MySQL5 I/O stats (needs the MySQL PMDA)

            show the MySQL5 keys stats (needs the MySQL PMDA)

            show the MySQL I/O stats (needs the MySQL PMDA)

            show the MySQL keys stats (needs the MySQL PMDA)

            show postfix queue sizes (needs the Postfix PMDA)

            show Redis stats (needs the Redis PMDA)

            show sendmail queue size (needs the Sendmail PMDA)


       Anyone can create additional, custom pcp-dstat plugin
       configuration files, for any metrics - the list of available
       metrics can be produced by either the pminfo(1) or pmprobe(1)

       The following do not yet have metrics backing them, but have been
       included from the original Dstat utility.  Please contact
       <pcp@groups.io> if you need or implement any of these, and we'll
       work with you to get them included.

            battery in percentage (needs an ACPI PMDA)

            battery remaining in hours, minutes (needs an ACPI PMDA)

            CPU frequency in percentage (needs an ACPI PMDA)

            number of dbus connections (needs a python-dbus PMDA)

            fan speed (needs an ACPI PMDA)

            show software raid (MD driver) progress and speed (needs new
            disk.md metrics)

            show power usage (needs an ACPI PMDA)

            show qmail queue sizes (needs qmail)

            show squid usage statistics (needs a Squid PMDA)

            system temperature sensors (needs an ACPI PMDA)

            show VMware CPU stats from hypervisor (needs a VMware PMDA)

            show VMware memory stats from hypervisor (needs a VMware

            show advanced VMware memory stats from hypervisor (needs a
            VMware PMDA)

            show VMware ESX kernel vmhba stats (needs a VMware PMDA)

            show VMware ESX kernel interrupt stats (needs a VMware PMDA)

            show VMware ESX kernel port stats (needs a VMware PMDA)

            show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)

            show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)

            show OpenVZ user beancounters (needs an OpenVZ PMDA)

            wireless link quality and signal to noise ratio (needs Linux
            PMDA metrics)

            show ZFS arc stats (needs a Linux ZFS PMDA)

            show ZFS l2arc stats (needs a Linux ZFS PMDA)

            show ZFS zil stats (needs a Linux ZFS PMDA)


       When invoking pcp-dstat with a delay greater than 1 second and
       without the --noupdate option, it will show intermediate updates,
       i.e., the first time a 1 second average, the second update a 2
       second average, etc. until the delay has been reached.

       So in case you specified a delay of 10, the 9 intermediate
       updates are NOT snapshots, they are averages over the time that
       passed since the last final update.  The end result is that you
       get a 10 second average on a new line, just like with vmstat(1).

EXAMPLES         top

       Using pcp-dstat to relate disk-throughput with network-usage
       (eth0), total CPU-usage and system counters:

            $ pcp dstat -dnyc -N eth0 -C total -f 5

       Using the time plugin together with cpu, net, disk, system, load
       and proc plugins:

            $ pcp dstat -tcndylp

       This is identical to:

            $ pcp dstat --time --cpu --net --disk --sys --load --proc

       Using pcp-dstat to report 10 samples from metrics recorded in a
       PCP archive 20180729 from 2:30 AM:
        $ pcp --origin '@02:30' -a 20180729 dstat --time --cpu-adv --sys 1 10

       Examine the same metrics live from a remote host:

            $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10

FILES         top

            private per-user configuration files

            system-wide configuration files

ENVIRONMENT         top

       Internal plugins behaviour can be changed through environment

              strftime(3) format string for reporting time (see --time)


       Environment variables with the prefix PCP_ are used to
       parameterize the file and directory names used by PCP.  On each
       installation, the file /etc/pcp.conf contains the local values
       for these variables.  The $PCP_CONF variable may be used to
       specify an alternative configuration file, as described in

       For environment variables affecting PCP tools, see

AUTHORS         top

       The Dstat utility was initially written by Dag Wieers

       The Dstat homepage is at http://dag.wieers.com/home-made/dstat/ .

       This manpage was initially written by Andrew Pollock
       <apollock@debian.org> for the Debian GNU/Linux system.

       The pcp-dstat utility is written and maintained by the PCP
       developers <pcp@groups.io>.

       The PCP homepage is at https://pcp.io/ .

SEE ALSO         top

       PCPIntro(1), pcp(1), pmcd(1), pminfo(1), pmlogger(1), pmprobe(1),
       vmstat(1), pmGetOptions(3), strftime(3), PMNS(5), pcp.conf(5),
       pcp-dstat(5) and utmp(5).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨http://www.pcp.io/⟩.  If you have a bug report for this manual
       page, send it to pcp@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2021-08-27.
       (At that time, the date of the most recent commit that was found
       in the repository was 2021-08-27.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot               PCP                      PCP-DSTAT(1)

Pages that refer to this page: pcp-dstat(5)