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
11       interfaces]   [-o   output-file]   [-S  swap-devices]  [--bits]  [--bw]
12       [--color] [--float] [--integer] [--nocolor] [--noheaders]  [--noupdate]
13       [--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-
42       related  reporting  only),  or  sourced  from  the system-wide location
43       ($PCP_ETC_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-
90            device 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
98            related 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
167              device
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       -f, --full
243              expand -C, -D, -I, -N and -S discovery lists
244
245       -v, --vmstat
246              equals -pmgdsc -D total
247
248       --bits force bits for values expressed in bytes
249
250       --float
251              force float values on screen (mutually exclusive with --integer)
252
253       --integer
254              force integer values on screen (mutually exclusive with --float)
255
256       --bw, --blackonwhite
257              change colors for white background terminal
258
259       --nocolor
260              disable colors
261
262       --noheaders
263              disable repetitive headers
264
265       --noupdate
266              disable intermediate updates when delay greater than 1.
267
268       -o file, --output=file
269              write CSV (Comma-Separated Value) format output to a file.
270
271       -p file, --pidfile=file
272              write the process identifier to a given file.
273

OPTIONAL METRICS PLUGINS

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

HISTORICAL METRICS PLUGINS

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

INTERMEDIATE UPDATES

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

EXAMPLES

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

FILES

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

ENVIRONMENT

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

PCP ENVIRONMENT

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

AUTHORS

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

SEE ALSO

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