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]  [--noupdate]  [--list]
13       [--pidfile pid-file] [--plugin] [--all-plugins] [delay [count]]
14

DESCRIPTION

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

OPTIONS

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

OPTIONAL METRICS PLUGINS

274       Some pcp-dstat configuration files require the installation of optional
275       Performance Metric Domain Agents, above  and  beyond  the  default  in‐
276       stalled set.
277
278       --gpfs
279            GPFS read/write I/O (needs the GPFS PMDA)
280
281       --gpfs-ops
282            GPFS filesystem operations (needs the GPFS PMDA)
283
284       --innodb-buffer
285            show innodb buffer stats (needs the MySQL PMDA)
286
287       --innodb-io
288            show innodb I/O stats (needs the MySQL PMDA)
289
290       --innodb-ops
291            show innodb operations counters (needs the MySQL PMDA)
292
293       --lustre
294            show lustre I/O throughput (needs the Lustre PMDA)
295
296       --memcache-hits
297            show the number of hits and misses from memcache
298
299       --mysql5-cmds
300            show the MySQL5 command stats (needs the MySQL PMDA)
301
302       --mysql5-conn
303            show the MySQL5 connection stats (needs the MySQL PMDA)
304
305       --mysql5-innodb
306            show the MySQL5 innodb stats (needs the MySQL PMDA)
307
308       --mysql5-io
309            show the MySQL5 I/O stats (needs the MySQL PMDA)
310
311       --mysql5-keys
312            show the MySQL5 keys stats (needs the MySQL PMDA)
313
314       --mysql-io
315            show the MySQL I/O stats (needs the MySQL PMDA)
316
317       --mysql-keys
318            show the MySQL keys stats (needs the MySQL PMDA)
319
320       --postfix
321            show postfix queue sizes (needs the Postfix PMDA)
322
323       --redis
324            show Redis stats (needs the Redis PMDA)
325
326       --sendmail
327            show sendmail queue size (needs the Sendmail PMDA)
328

HISTORICAL METRICS PLUGINS

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

INTERMEDIATE UPDATES

412       When  invoking pcp-dstat with a delay greater than 1 second and without
413       the --noupdate option, it will show  intermediate  updates,  i.e.,  the
414       first  time  a  1 second average, the second update a 2 second average,
415       etc. until the delay has been reached.
416
417       So in case you specified a delay of 10, the 9 intermediate updates  are
418       NOT  snapshots,  they  are averages over the time that passed since the
419       last final update.  The end result is that you get a 10 second  average
420       on a new line, just like with vmstat(1).
421

EXAMPLES

423       Using  pcp-dstat  to  relate disk-throughput with network-usage (eth0),
424       total CPU-usage and system counters:
425
426            $ pcp dstat -dnyc -N eth0 -C total -f 5
427
428       Using the time plugin together with cpu, net, disk,  system,  load  and
429       proc plugins:
430
431            $ pcp dstat -tcndylp
432
433       This is identical to:
434
435            $ pcp dstat --time --cpu --net --disk --sys --load --proc
436
437       Using pcp-dstat to report 10 samples from metrics recorded in a PCP ar‐
438       chive 20180729 from 2:30 AM:
439        $ pcp --origin '@02:30' -a 20180729 dstat --time --cpu-adv --sys 1 10
440
441       Examine the same metrics live from a remote host:
442
443            $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10
444
445

FILES

447       $HOME/.pcp/dstat/
448            private per-user configuration files
449
450       $PCP_SYSCONF_DIR/dstat/
451            system-wide configuration files
452

ENVIRONMENT

454       Internal plugins behaviour can be  changed  through  environment  vari‐
455       ables.
456
457       DSTAT_TIMEFMT
458              strftime(3) format string for reporting time (see --time)
459

PCP ENVIRONMENT

461       Environment variables with the prefix PCP_ are used to parameterize the
462       file and directory names used by PCP.  On each installation,  the  file
463       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
464       $PCP_CONF variable may be used to specify an alternative  configuration
465       file, as described in pcp.conf(5).
466
467       For environment variables affecting PCP tools, see pmGetOptions(3).
468

AUTHORS

470       The Dstat utility was initially written by Dag Wieers <dag@wieers.com>.
471
472       The Dstat homepage is at http://dag.wieers.com/home-made/dstat/.
473
474       This  manpage  was  initially  written  by Andrew Pollock <apollock@de‐
475       bian.org> for the Debian GNU/Linux system.
476
477       The pcp-dstat utility is written and maintained by the  PCP  developers
478       <pcp@groups.io>.
479
480       The PCP homepage is at https://pcp.io/.
481

SEE ALSO

483       PCPIntro(1),  pcp(1),  pmcd(1), pminfo(1), pmlogger(1), pmprobe(1), vm‐
484       stat(1),  pmGetOptions(3),  strftime(3),  PMNS(5),  pcp.conf(5),   pcp-
485       dstat(5) and utmp(5).
486
487
488
489Performance Co-Pilot                  PCP                         PCP-DSTAT(1)
Impressum