# pcp-dstat

## NAME



           **pcp-dstat** - versatile tool for generating system resource
           statistics
    


## SYNOPSIS



           **pcp**[_pcp options_] **dstat**[**-acdfghilmnpqrstvVy?**]  [**-C** _cpus_] [**-G**
           _gpus_] [**-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**] [**--nomissed**] [**--noupdate**] [**--list**] [**--pidfile** _pid-_
           _file_] [**--**_plugin_] [**--all-plugins**] [_delay_ [_count_]]
    


## DESCRIPTION



           **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
           efficient.
    
           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
           (**$HOME/.pcp/dstat**).
    
           The list of all available plugins can be seen using the **--list**
           dstat command line option.
    


## OPTIONS



           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
    
           **--plugin-name**
                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
    
           **--amd-gpu** , **--nvidia-gpu**
                enable stats for the specific GPU architecture (utilization,
                memory use)
    
           **-G** _0,3_
                include GPU0 and GPU3 (when using **--amd-gpu** or **--nvidia-gpu**)
    
           **-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**
                plugin)
    
           **--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**
                plugins
    
           **--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**)
    
           **--net-packets**
                show the number of packets received and transmitted
    
           **-p** , **--proc**
                enable process stats (runnable, uninterruptible, new)
    
           **--proc-count**
                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
                  precision)
    
           **-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)
    
           **--cpu-adv**
                  enable advanced CPU stats
    
           **--cpu-use**
                  enable only CPU usage stats
    
           **--disk-avgqu**
                  average queue length of the requests that were issued to
                  the device
    
           **--disk-avgrq**
                  average size (in sectors) of the requests that were issued
                  to the device
    
           **--disk-svctm**
                  average service time (in milliseconds) for I/O requests
                  that were issued to the device
    
           **--disk-tps**
                  number of transfers per second that were issued to the
                  device
    
           **--disk-util**
                  percentage of CPU time during which I/O requests were
                  issued to the device (bandwidth utilization for the device)
    
           **--disk-wait**
                  average time (in milliseconds) for I/O requests issued to
                  the device to be served
    
           **--fs** , **--filesystem**
                  enable filesystem stats (open files, inodes)
    
           **--freespace**
                  per filesystem used and available space
    
           **--ipc** enable ipc stats (message queue, semaphores, shared memory)
    
           **--lock** enable file lock stats (posix, flock, read, write)
    
           **--mem-adv**
                  enable advanced memory stats
    
           **--raw** enable raw stats (raw sockets)
    
           **--socket**
                  enable socket stats (total, tcp, udp, raw, ip-fragments)
    
           **--tcp** enable tcp stats (listen, established, syn, time_wait,
                  close)
    
           **--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)
    
           **--vm-adv**
                  enable advance virtual memory stats (steal, scanK, scanD,
                  pgoru, astll)
    
           **--nfs3** show NFS v3 client operations
    
           **--nfs3-ops**
                  show extended NFS v3 client operations
    
           **--nfsd3**
                  show NFS v3 server operations
    
           **--nfsd3-ops**
                  show extended NFS v3 server operations
    
           **--nfsd4-ops**
                  show extended NFS v4 server operations
    
           **--nfsstat4**
                  show NFS v4 stats
    
           **--rpc** show remote procedure call (RPC) client calls stats
    
           **--rpcd** show remote procedure call (RPC) server calls stats
    
           **--top-bio**
                  show most expensive block I/O process
    
           **--top-bio-adv**
                  show most expensive block I/O process (incl. PID and other
                  stats)
    
           **--top-childwait**
                  show process waiting for child the most
    
           **--top-cpu**
                  show most expensive CPU process
    
           **--top-cpu-adv**
                  show most expensive CPU process (incl. PID and other stats)
    
           **--top-cputime**
                  show process using the most CPU time (in milliseconds)
    
           **--top-cputime-avg**
                  show process with the highest average timeslice (in
                  milliseconds)
    
           **--top-io**
                  show most expensive I/O process
    
           **--top-io-adv**
                  show most expensive I/O process (incl. PID and other stats)
    
           **--top-latency**
                  show process with highest total latency (in milliseconds)
    
           **--top-latency-avg**
                  show process with the highest average latency (in
                  milliseconds)
    
           **--top-mem**
                  show process using the most memory
    
           **--top-oom**
                  show process that will be killed by the out-of-memory (OOM)
                  killer the first
    
           **-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
    
           **--float**
                  force float values on screen (mutually exclusive with
                  **--integer**)
    
           **--integer**
                  force integer values on screen (mutually exclusive with
                  **--float**)
    
           **--bw** , **--blackonwhite**
                  change colors for white background terminal
    
           **--nocolor**
                  disable colors
    
           **--noheaders**
                  disable repetitive headers
    
           **--nomissed**
                  disable missed ticks warnings for intermediate samples.
    
           **--noupdate**
                  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_.
    


## OPTIONAL METRICS PLUGINS



           Some **pcp-dstat** configuration files require the installation of
           optional Performance Metric Domain Agents, above and beyond the
           default installed set.
    
           **--battery**
                remaining battery charge in percentage (needs the Denki PMDA)
    
           **--gpfs**
                GPFS read/write I/O (needs the GPFS PMDA)
    
           **--gpfs-ops**
                GPFS filesystem operations (needs the GPFS PMDA)
    
           **--innodb-buffer**
                show innodb buffer stats (needs the MySQL PMDA)
    
           **--innodb-io**
                show innodb I/O stats (needs the MySQL PMDA)
    
           **--innodb-ops**
                show innodb operations counters (needs the MySQL PMDA)
    
           **--lustre**
                show lustre I/O throughput (needs the Lustre PMDA)
    
           **--memcache-hits**
                show the number of hits and misses from memcache (needs the
                Memcached PMDA)
    
           **--mysql5-cmds**
                show the MySQL5 command stats (needs the MySQL PMDA)
    
           **--mysql5-conn**
                show the MySQL5 connection stats (needs the MySQL PMDA)
    
           **--mysql5-innodb**
                show the MySQL5 innodb stats (needs the MySQL PMDA)
    
           **--mysql5-io**
                show the MySQL5 I/O stats (needs the MySQL PMDA)
    
           **--mysql5-keys**
                show the MySQL5 keys stats (needs the MySQL PMDA)
    
           **--mysql-io**
                show the MySQL I/O stats (needs the MySQL PMDA)
    
           **--mysql-keys**
                show the MySQL keys stats (needs the MySQL PMDA)
    
           **--postfix**
                show postfix queue sizes (needs the Postfix PMDA)
    
           **--redis**
                show Redis stats (needs the Redis PMDA)
    
           **--sendmail**
                show sendmail queue size (needs the Sendmail PMDA)
    
           **--zfs-arc**
                show ZFS arc stats (needs the ZFS PMDA)
    
           **--zfs-l2arc**
                show ZFS l2arc stats (needs the ZFS PMDA)
    
           **--zfs-zil**
                show ZFS zil stats (needs the ZFS PMDA)
    


## HISTORICAL METRICS PLUGINS



           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)
           command.
    
           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-remain**
                  battery remaining in hours, minutes (needs an ACPI PMDA)
    
           **--cpufreq**
                  CPU frequency in percentage (needs an ACPI PMDA)
    
           **--dbus** number of dbus connections (needs a python-dbus PMDA)
    
           **--fan** fan speed (needs an ACPI PMDA)
    
           **--md-status**
                  show software raid (MD driver) progress and speed (needs
                  new _disk.md_ metrics)
    
           **--power**
                  show power usage (needs an ACPI PMDA)
    
           **--qmail**
                  show qmail queue sizes (needs qmail)
    
           **--squid**
                  show squid usage statistics (needs a Squid PMDA)
    
           **--thermal**
                  system temperature sensors (needs an ACPI PMDA)
    
           **--vm-cpu**
                  show VMware CPU stats from hypervisor (needs a VMware PMDA)
    
           **--vm-mem**
                  show VMware memory stats from hypervisor (needs a VMware
                  PMDA)
    
           **--vm-mem-adv**
                  show advanced VMware memory stats from hypervisor (needs a
                  VMware PMDA)
    
           **--vmk-hba**
                  show VMware ESX kernel vmhba stats (needs a VMware PMDA)
    
           **--vmk-int**
                  show VMware ESX kernel interrupt stats (needs a VMware
                  PMDA)
    
           **--vmk-nic**
                  show VMware ESX kernel port stats (needs a VMware PMDA)
    
           **--vz-cpu**
                  show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)
    
           **--vz-io**
                  show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)
    
           **--vz-ubc**
                  show OpenVZ user beancounters (needs an OpenVZ PMDA)
    
           **--wifi** wireless link quality and signal to noise ratio (needs
                  Linux PMDA metrics)
    


## INTERMEDIATE UPDATES



           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



           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



           $HOME _/.pcp/dstat/_
                private per-user configuration files
    
           $PCP_SYSCONF_DIR _/dstat/_
                system-wide configuration files
    


## ENVIRONMENT



           Internal plugins behaviour can be changed through environment
           variables.
    
           _DSTAT_TIMEFMT_
                  strftime(3) format string for reporting time (see **--time**)
    


## PCP ENVIRONMENT



           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 pcp.conf(5).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


* * *