1PCP-DSTAT(1)                General Commands Manual               PCP-DSTAT(1)
2
3
4

NAME

6       pcp-dstat - versatile tool for generating system resource statistics
7

SYNOPSIS

9       pcp  [pcp options]  dstat  [-acdfghilmnpqrstvVy?]  [-C cpus] [-D disks]
10       [-L DM devices] [-M MD devices] [-P partitions] [-I interrupts] [-N in‐
11       terfaces]  [-o output-file] [-S swap-devices] [--bits] [--bw] [--color]
12       [--float] [--integer] [--nocolor] [--noheaders]  [--nomissed]  [--noup‐
13       date]  [--list]  [--pidfile pid-file] [--plugin] [--all-plugins] [delay
14       [count]]
15

DESCRIPTION

17       pcp-dstat is a general performance analysis tool allowing you  to  view
18       multiple  system  resources instantly, for example you can compare disk
19       usage in combination with interrupts from a disk controller, or compare
20       the network bandwidth numbers directly with the disk throughput (in the
21       same interval).
22
23       It also cleverly gives you the most detailed information in columns and
24       clearly  indicates  in what magnitude and unit the output is being dis‐
25       played.  Less confusion, fewer mistakes, more efficient.
26
27       The delay is the delay in seconds between each update, and the count is
28       the  number of updates to display before exiting.  The default delay is
29       1 second and count is unspecified (run until interrupted or end of  ar‐
30       chive is reached).
31
32       This latest generation of Dstat, pcp-dstat, allows for analysis of his‐
33       torical performance data (in the PCP archive format created  by  pmlog‐
34       ger(1)),  as  well  as distributed systems analysis of live performance
35       data from remote hosts running the pmcd(1) process.
36
37       The original Dstat notion of ``plugins'' is replaced by  use  of  named
38       metrics  in  a Performance Metric Name Space (PMNS(5)) supplied by Per‐
39       formance Metric Domain Agents (PMDAs).  Metrics  and  other  formatting
40       information  is  now  specified  as  plugin configuration files in pcp-
41       dstat(5) format.  This new style of plugin is either built-in (time-re‐
42       lated  reporting  only),  or  sourced  from  the  system-wide  location
43       ($PCP_SYSCONF_DIR/dstat) and/or sourced from an individual users set of
44       personal plugins ($HOME/.pcp/dstat).
45
46       The  list  of  all available plugins can be seen using the --list dstat
47       command line option.
48

OPTIONS

50       When invoked via  the  pcp(1)  command,  the  -h/--host,  -a/--archive,
51       -O/--origin,  -Z/--timezone  and several other pcp options become indi‐
52       rectly available; refer to PCPIntro(1) for a  complete  description  of
53       these options.
54
55       The additional command line options available for pcp-dstat are:
56
57       --list list all available plugin names
58
59       --plugin-name
60            enable any plugin by name
61
62       -a, --all
63            equals -cdngy (default plugin set)
64
65       -c, --cpu
66            enable  CPU stats (system, user, idle, wait); for more CPU related
67            stats also see --cpu-adv and --cpu-use
68
69       -C 0,3,total
70            include CPU0, CPU3 and total (when using  -c/--cpu);  use  all  to
71            show all CPUs
72
73       -d, --disk
74            enable  disk stats (read, write); for more disk related stats look
75            into the other --disk plugins
76
77       -D total,hda
78            include total and hda (when using -d/--disk or --disk-tps plugin)
79
80       --dm, --device-mapper
81            enable device mapper stats (read, write); for  more  device-mapper
82            related stats look into the other --dm plugins
83
84       --L total,root,home
85            include  total,  root and home (when using --dm/--device-mapper or
86            --dm-tps plugin)
87
88       --md, --multi-device
89            enable multi-device driver stats (read, write); for more multi-de‐
90            vice driver related stats look into the other --md plugins
91
92       --M total,md-0
93            include total and md-0 (when using --md/--multi-device or --md-tps
94            plugin)
95
96       --part, --partition
97            enable disk partition stats (read, write); for more partition  re‐
98            lated stats look into the other --part plugins
99
100       --P total,sda2
101            include  total  and sda2 (when using --part/--partition or --part-
102            tps plugin)
103
104       -g, --page
105            enable page stats (page in, page out)
106
107       -i, --int
108            enable interrupt stats
109
110       -I 5,10
111            include interrupt 5 and 10 (when using -i/--int)
112
113       -l, --load
114            enable load average stats (1 min, 5 mins, 15 mins)
115
116       -m, --mem
117            enable memory stats (used, buffers, cache, free); for more  memory
118            related stats also try --mem-adv and --swap
119
120       -n, --net
121            enable network stats (receive, send)
122
123       -N eth1,total
124            include eth1 and total (when using -n/--net)
125
126       --net-packets
127            show the number of packets received and transmitted
128
129       -p, --proc
130            enable process stats (runnable, uninterruptible, new)
131
132       --proc-count
133            show total number of processes
134
135       -r, --io
136            enable I/O request stats (read, write requests)
137
138       -s, --swap
139            enable swap stats (used, free)
140
141       -S swap1,total
142            include swap1 and total (when using -s/--swap)
143
144       --snooze show time spent between updates in seconds
145
146       -t, --time
147              enable  time/date  output (try --time-adv for millisecond preci‐
148              sion)
149
150       -T, --epoch
151              enable time counter (seconds since epoch, or millisecond  preci‐
152              sion from the --epoch-adv plugin)
153
154       -y, --sys
155              enable system stats (interrupts, context switches)
156
157       --aio  enable aio stats (asynchronous I/O)
158
159       --cpu-adv
160              enable advanced CPU stats
161
162       --cpu-use
163              enable only CPU usage stats
164
165       --disk-avgqu
166              average queue length of the requests that were issued to the de‐
167              vice
168
169       --disk-avgrq
170              average size (in sectors) of the requests that  were  issued  to
171              the device
172
173       --disk-svctm
174              average  service  time  (in  milliseconds) for I/O requests that
175              were issued to the device
176
177       --disk-tps
178              number of transfers per second that were issued to the device
179
180       --disk-util
181              percentage of CPU time during which I/O requests were issued  to
182              the device (bandwidth utilization for the device)
183
184       --disk-wait
185              average  time  (in  milliseconds) for I/O requests issued to the
186              device to be served
187
188       --fs, --filesystem
189              enable filesystem stats (open files, inodes)
190
191       --freespace
192              per filesystem used and available space
193
194       --ipc  enable ipc stats (message queue, semaphores, shared memory)
195
196       --lock enable file lock stats (posix, flock, read, write)
197
198       --mem-adv
199              enable advanced memory stats
200
201       --raw  enable raw stats (raw sockets)
202
203       --socket
204              enable socket stats (total, tcp, udp, raw, ip-fragments)
205
206       --tcp  enable tcp stats (listen, established, syn, time_wait, close)
207
208       --udp  enable udp stats (listen, active)
209
210       --unix enable unix stats (datagram, stream, listen, active)
211
212       --utmp shows login information from utmp(5)
213
214       --vm   enable virtual memory stats (hard pagefaults,  soft  pagefaults,
215              allocated, free)
216
217       --vm-adv
218              enable advance virtual memory stats (steal, scanK, scanD, pgoru,
219              astll)
220
221       --nfs3 show NFS v3 client operations
222
223       --nfs3-ops
224              show extended NFS v3 client operations
225
226       --nfsd3
227              show NFS v3 server operations
228
229       --nfsd3-ops
230              show extended NFS v3 server operations
231
232       --nfsd4-ops
233              show extended NFS v4 server operations
234
235       --nfsstat4
236              show NFS v4 stats
237
238       --rpc  show remote procedure call (RPC) client calls stats
239
240       --rpcd show remote procedure call (RPC) server calls stats
241
242       --top-bio
243              show most expensive block I/O process
244
245       --top-bio-adv
246              show most expensive block  I/O  process  (incl.  PID  and  other
247              stats)
248
249       --top-childwait
250              show process waiting for child the most
251
252       --top-cpu
253              show most expensive CPU process
254
255       --top-cpu-adv
256              show most expensive CPU process (incl. PID and other stats)
257
258       --top-cputime
259              show process using the most CPU time (in milliseconds)
260
261       --top-cputime-avg
262              show  process  with  the highest average timeslice (in millisec‐
263              onds)
264
265       --top-io
266              show most expensive I/O process
267
268       --top-io-adv
269              show most expensive I/O process (incl. PID and other stats)
270
271       --top-latency
272              show process with highest total latency (in milliseconds)
273
274       --top-latency-avg
275              show process with the highest average latency (in milliseconds)
276
277       --top-mem
278              show process using the most memory
279
280       --top-oom
281              show process that will be  killed  by  the  out-of-memory  (OOM)
282              killer the first
283
284       -f, --full
285              expand -C, -D, -I, -N and -S discovery lists
286
287       -v, --vmstat
288              equals -pmgdsc -D total
289
290       --bits force bits for values expressed in bytes
291
292       --float
293              force float values on screen (mutually exclusive with --integer)
294
295       --integer
296              force integer values on screen (mutually exclusive with --float)
297
298       --bw, --blackonwhite
299              change colors for white background terminal
300
301       --nocolor
302              disable colors
303
304       --noheaders
305              disable repetitive headers
306
307       --nomissed
308              disable missed ticks warnings for intermediate samples.
309
310       --noupdate
311              disable intermediate updates when delay greater than 1.
312
313       -o file, --output=file
314              write CSV (Comma-Separated Value) format output to a file.
315
316       -p file, --pidfile=file
317              write the process identifier to a given file.
318

OPTIONAL METRICS PLUGINS

320       Some pcp-dstat configuration files require the installation of optional
321       Performance Metric Domain Agents, above  and  beyond  the  default  in‐
322       stalled set.
323
324       --battery
325            remaining battery charge in percentage (needs the Denki PMDA)
326
327       --gpfs
328            GPFS read/write I/O (needs the GPFS PMDA)
329
330       --gpfs-ops
331            GPFS filesystem operations (needs the GPFS PMDA)
332
333       --innodb-buffer
334            show innodb buffer stats (needs the MySQL PMDA)
335
336       --innodb-io
337            show innodb I/O stats (needs the MySQL PMDA)
338
339       --innodb-ops
340            show innodb operations counters (needs the MySQL PMDA)
341
342       --lustre
343            show lustre I/O throughput (needs the Lustre PMDA)
344
345       --memcache-hits
346            show  the  number of hits and misses from memcache (needs the Mem‐
347            cached PMDA)
348
349       --mysql5-cmds
350            show the MySQL5 command stats (needs the MySQL PMDA)
351
352       --mysql5-conn
353            show the MySQL5 connection stats (needs the MySQL PMDA)
354
355       --mysql5-innodb
356            show the MySQL5 innodb stats (needs the MySQL PMDA)
357
358       --mysql5-io
359            show the MySQL5 I/O stats (needs the MySQL PMDA)
360
361       --mysql5-keys
362            show the MySQL5 keys stats (needs the MySQL PMDA)
363
364       --mysql-io
365            show the MySQL I/O stats (needs the MySQL PMDA)
366
367       --mysql-keys
368            show the MySQL keys stats (needs the MySQL PMDA)
369
370       --postfix
371            show postfix queue sizes (needs the Postfix PMDA)
372
373       --redis
374            show Redis stats (needs the Redis PMDA)
375
376       --sendmail
377            show sendmail queue size (needs the Sendmail PMDA)
378
379       --zfs-arc
380            show ZFS arc stats (needs the ZFS PMDA)
381
382       --zfs-l2arc
383            show ZFS l2arc stats (needs the ZFS PMDA)
384
385       --zfs-zil
386            show ZFS zil stats (needs the ZFS PMDA)
387

HISTORICAL METRICS PLUGINS

389       Anyone can create additional,  custom  pcp-dstat  plugin  configuration
390       files,  for any metrics - the list of available metrics can be produced
391       by either the pminfo(1) or pmprobe(1) command.
392
393       The following do not yet have metrics backing them, but have  been  in‐
394       cluded from the original Dstat utility.  Please contact <pcp@groups.io>
395       if you need or implement any of these, and we'll work with you  to  get
396       them included.
397
398       --battery-remain
399              battery remaining in hours, minutes (needs an ACPI PMDA)
400
401       --cpufreq
402              CPU frequency in percentage (needs an ACPI PMDA)
403
404       --dbus number of dbus connections (needs a python-dbus PMDA)
405
406       --fan  fan speed (needs an ACPI PMDA)
407
408       --md-status
409              show  software  raid  (MD  driver) progress and speed (needs new
410              disk.md metrics)
411
412       --power
413              show power usage (needs an ACPI PMDA)
414
415       --qmail
416              show qmail queue sizes (needs qmail)
417
418       --squid
419              show squid usage statistics (needs a Squid PMDA)
420
421       --thermal
422              system temperature sensors (needs an ACPI PMDA)
423
424       --vm-cpu
425              show VMware CPU stats from hypervisor (needs a VMware PMDA)
426
427       --vm-mem
428              show VMware memory stats from hypervisor (needs a VMware PMDA)
429
430       --vm-mem-adv
431              show advanced VMware  memory  stats  from  hypervisor  (needs  a
432              VMware PMDA)
433
434       --vmk-hba
435              show VMware ESX kernel vmhba stats (needs a VMware PMDA)
436
437       --vmk-int
438              show VMware ESX kernel interrupt stats (needs a VMware PMDA)
439
440       --vmk-nic
441              show VMware ESX kernel port stats (needs a VMware PMDA)
442
443       --vz-cpu
444              show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)
445
446       --vz-io
447              show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)
448
449       --vz-ubc
450              show OpenVZ user beancounters (needs an OpenVZ PMDA)
451
452       --wifi wireless  link  quality  and  signal to noise ratio (needs Linux
453              PMDA metrics)
454

INTERMEDIATE UPDATES

456       When invoking pcp-dstat with a delay greater than 1 second and  without
457       the  --noupdate  option,  it  will show intermediate updates, i.e., the
458       first time a 1 second average, the second update a  2  second  average,
459       etc. until the delay has been reached.
460
461       So  in case you specified a delay of 10, the 9 intermediate updates are
462       NOT snapshots, they are averages over the time that  passed  since  the
463       last  final update.  The end result is that you get a 10 second average
464       on a new line, just like with vmstat(1).
465

EXAMPLES

467       Using pcp-dstat to relate disk-throughput  with  network-usage  (eth0),
468       total CPU-usage and system counters:
469
470            $ pcp dstat -dnyc -N eth0 -C total -f 5
471
472       Using  the  time  plugin together with cpu, net, disk, system, load and
473       proc plugins:
474
475            $ pcp dstat -tcndylp
476
477       This is identical to:
478
479            $ pcp dstat --time --cpu --net --disk --sys --load --proc
480
481       Using pcp-dstat to report 10 samples from metrics recorded in a PCP ar‐
482       chive 20180729 from 2:30 AM:
483        $ pcp --origin '@02:30' -a 20180729 dstat --time --cpu-adv --sys 1 10
484
485       Examine the same metrics live from a remote host:
486
487            $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10
488
489

FILES

491       $HOME/.pcp/dstat/
492            private per-user configuration files
493
494       $PCP_SYSCONF_DIR/dstat/
495            system-wide configuration files
496

ENVIRONMENT

498       Internal  plugins  behaviour  can  be changed through environment vari‐
499       ables.
500
501       DSTAT_TIMEFMT
502              strftime(3) format string for reporting time (see --time)
503

PCP ENVIRONMENT

505       Environment variables with the prefix PCP_ are used to parameterize the
506       file  and  directory names used by PCP.  On each installation, the file
507       /etc/pcp.conf contains the  local  values  for  these  variables.   The
508       $PCP_CONF  variable may be used to specify an alternative configuration
509       file, as described in pcp.conf(5).
510
511       For environment variables affecting PCP tools, see pmGetOptions(3).
512

AUTHORS

514       The Dstat utility was initially written by Dag Wieers <dag@wieers.com>.
515
516       The Dstat homepage is at http://dag.wieers.com/home-made/dstat/.
517
518       This manpage was initially  written  by  Andrew  Pollock  <apollock@de‐
519       bian.org> for the Debian GNU/Linux system.
520
521       The  pcp-dstat  utility is written and maintained by the PCP developers
522       <pcp@groups.io>.
523
524       The PCP homepage is at https://pcp.io/.
525

SEE ALSO

527       PCPIntro(1), pcp(1), pmcd(1), pminfo(1), pmlogger(1),  pmprobe(1),  vm‐
528       stat(1),   pmGetOptions(3),  strftime(3),  PMNS(5),  pcp.conf(5),  pcp-
529       dstat(5) and utmp(5).
530
531
532
533Performance Co-Pilot                  PCP                         PCP-DSTAT(1)
Impressum