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 [dstat options] [delay [count]]
10

DESCRIPTION

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

OPTIONS

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

OPTIONAL METRICS PLUGINS

288       Some pcp-dstat configuration files require the installation of optional
289       Performance   Metric  Domain  Agents,  above  and  beyond  the  default
290       installed set.
291
292       --innodb-buffer
293            show innodb buffer stats (needs the MySQL PMDA)
294
295       --innodb-io
296            show innodb I/O stats (needs the MySQL PMDA)
297
298       --innodb-ops
299            show innodb operations counters (needs the MySQL PMDA)
300
301       --lustre
302            show lustre I/O throughput (needs the Lustre PMDA)
303
304       --memcache-hits
305            show the number of hits and misses from memcache
306
307       --mysql5-cmds
308            show the MySQL5 command stats (needs the MySQL PMDA)
309
310       --mysql5-conn
311            show the MySQL5 connection stats (needs the MySQL PMDA)
312
313       --mysql5-innodb
314            show the MySQL5 innodb stats (needs the MySQL PMDA)
315
316       --mysql5-io
317            show the MySQL5 I/O stats (needs the MySQL PMDA)
318
319       --mysql5-keys
320            show the MySQL5 keys stats (needs the MySQL PMDA)
321
322       --mysql-io
323            show the MySQL I/O stats (needs the MySQL PMDA)
324
325       --mysql-keys
326            show the MySQL keys stats (needs the MySQL PMDA)
327
328       --postfix
329            show postfix queue sizes (needs the Postfix PMDA)
330
331       --redis
332            show Redis stats (needs the Redis PMDA)
333
334       --sendmail
335            show sendmail queue size (needs the Sendmail PMDA)
336

HISTORICAL METRICS PLUGINS

338       Anyone can create additional,  custom  pcp-dstat  plugin  configuration
339       files,  for any metrics - the list of available metrics can be produced
340       by either the pminfo(1) or pmprobe(1) command.
341
342       The following do not yet have  metrics  backing  them,  but  have  been
343       included   from   the   original   Dstat   utility.    Please   contact
344       <pcp@groups.io> if you need or implement any of these, and  we'll  work
345       with you to get them included.
346
347       --battery
348            battery in percentage (needs an ACPI PMDA)
349
350       --battery-remain
351            battery remaining in hours, minutes (needs an ACPI PMDA)
352
353       --cpufreq
354            CPU frequency in percentage (needs an ACPI PMDA)
355
356       --dbus
357            number of dbus connections (needs a python-dbus PMDA)
358
359       --fan
360            fan speed (needs an ACPI PMDA)
361
362       --gpfs
363            GPFS read/write I/O (needs mmpmon and a GPFS PMDA)
364
365       --gpfs-ops
366            GPFS filesystem operations (needs mmpmon and a GPFS PMDA)
367
368       --md-status
369            show  software  raid  (MD  driver)  progress  and speed (needs new
370            disk.md metrics)
371
372       --power
373            show power usage (needs an ACPI PMDA)
374
375       --qmail
376            show qmail queue sizes (needs qmail)
377
378       --squid
379            show squid usage statistics (needs a Squid PMDA)
380
381       --thermal
382            system temperature sensors (needs an ACPI PMDA)
383
384       --vm-cpu
385            show VMware CPU stats from hypervisor (needs a VMware PMDA)
386
387       --vm-mem
388            show VMware memory stats from hypervisor (needs a VMware PMDA)
389
390       --vm-mem-adv
391            show advanced VMware memory stats from hypervisor (needs a  VMware
392            PMDA)
393
394       --vmk-hba
395            show VMware ESX kernel vmhba stats (needs a VMware PMDA)
396
397       --vmk-int
398            show VMware ESX kernel interrupt stats (needs a VMware PMDA)
399
400       --vmk-nic
401            show VMware ESX kernel port stats (needs a VMware PMDA)
402
403       --vz-cpu
404            show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)
405
406       --vz-io
407            show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)
408
409       --vz-ubc
410            show OpenVZ user beancounters (needs an OpenVZ PMDA)
411
412       --wifi
413            wireless  link quality and signal to noise ratio (needs Linux PMDA
414            metrics)
415
416       --zfs-arc
417            show ZFS arc stats (needs a Linux ZFS PMDA)
418
419       --zfs-l2arc
420            show ZFS l2arc stats (needs a Linux ZFS PMDA)
421
422       --zfs-zil
423            show ZFS zil stats (needs a Linux ZFS PMDA)
424

INTERMEDIATE UPDATES

426       When invoking pcp-dstat with a delay greater than 1 second and  without
427       the  --noupdate  option,  it  will show intermediate updates, i.e., the
428       first time a 1 second average, the second update a  2  second  average,
429       etc. until the delay has been reached.
430
431       So  in case you specified a delay of 10, the 9 intermediate updates are
432       NOT snapshots, they are averages over the time that  passed  since  the
433       last  final update.  The end result is that you get a 10 second average
434       on a new line, just like with vmstat(1).
435

EXAMPLES

437       Using pcp-dstat to relate disk-throughput  with  network-usage  (eth0),
438       total CPU-usage and system counters:
439
440            $ pcp dstat -dnyc -N eth0 -C total -f 5
441
442       Using  the  time  plugin together with cpu, net, disk, system, load and
443       proc plugins:
444
445            $ pcp dstat -tcndylp
446
447       This is identical to:
448
449            $ pcp dstat --time --cpu --net --disk --sys --load --proc
450
451       Using pcp-dstat to report 10 samples from metrics recorded in a PCP ar‐
452       chive 20180729 from 2:30 AM:
453        $ pcp --origin '@02:30' -a 20180729 dstat --time --cpu-adv --sys 1 10
454
455       Examine the same metrics live from a remote host:
456
457            $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10
458
459

FILES

461       $HOME/.pcp/dstat/
462              private per-user configuration files
463
464       $PCP_SYSCONF_DIR/pcp/dstat/
465              system-wide configuration files
466

PCP ENVIRONMENT

468       Environment variables with the prefix PCP_ are used to parameterize the
469       file and directory names used by PCP.  On each installation,  the  file
470       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
471       $PCP_CONF variable may be used to specify an alternative  configuration
472       file, as described in pcp.conf(5).
473
474       For environment variables affecting PCP tools, see pmGetOptions(3).
475

ENVIRONMENT VARIABLES

477       Internal  plugins  behaviour  can  be changed through environment vari‐
478       ables.
479
480       DSTAT_TIMEFMT
481              strftime(3) format string for reporting time (see --time)
482

AUTHORS

484       The Dstat utility was initially written by Dag Wieers <dag@wieers.com>.
485
486       The Dstat homepage is at http://dag.wieers.com/home-made/dstat/.
487
488       This  manpage  was  initially  written   by   Andrew   Pollock   <apol‐
489       lock@debian.org> for the Debian GNU/Linux system.
490
491       The  pcp-dstat  utility is written and maintained by the PCP developers
492       <pcp@groups.io>.
493
494       The PCP homepage is at https://pcp.io/.
495

SEE ALSO

497       PCPIntro(1),  pcp(1),  pmcd(1),  pminfo(1),  pmlogger(1),   pmprobe(1),
498       pmrep(1),    vmstat(1),    pmGetOptions(3),    strftime(3),    PMNS(5),
499       pcp.conf(5), pmrep.conf(5) and utmp(5).
500
501
502
503Performance Co-Pilot                  PCP                         PCP-DSTAT(1)
Impressum