1PCP-DSTAT(1) General Commands Manual PCP-DSTAT(1)
2
6 pcp-dstat - versatile tool for generating system resource statistics
7
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
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 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 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 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 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 The list of all available plugins can be seen using the --list dstat
47 command line option.
48
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 The additional command line options available for pcp-dstat are:
56 --list list all available plugin names
58 --plugin-name
60 enable any plugin by name
61 -a, --all
63 equals -cdngy (default plugin set)
64 -c, --cpu
66 enable CPU stats (system, user, idle, wait); for more CPU related
67 stats also see --cpu-adv and --cpu-use
68 -C 0,3,total
70 include CPU0, CPU3 and total (when using -c/--cpu); use all to
71 show all CPUs
72 -d, --disk
74 enable disk stats (read, write); for more disk related stats look
75 into the other --disk plugins
76 -D total,hda
78 include total and hda (when using -d/--disk or --disk-tps plugin)
79 --dm, --device-mapper
81 enable device mapper stats (read, write); for more device-mapper
82 related stats look into the other --dm plugins
83 --L total,root,home
85 include total, root and home (when using --dm/--device-mapper or
86 --dm-tps plugin)
87 --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 --M total,md-0
93 include total and md-0 (when using --md/--multi-device or --md-tps
94 plugin)
95 --part, --partition
97 enable disk partition stats (read, write); for more partition re‐
98 lated stats look into the other --part plugins
99 --P total,sda2
101 include total and sda2 (when using --part/--partition or --part-
102 tps plugin)
103 -g, --page
105 enable page stats (page in, page out)
106 -i, --int
108 enable interrupt stats
109 -I 5,10
111 include interrupt 5 and 10 (when using -i/--int)
112 -l, --load
114 enable load average stats (1 min, 5 mins, 15 mins)
115 -m, --mem
117 enable memory stats (used, buffers, cache, free); for more memory
118 related stats also try --mem-adv and --swap
119 -n, --net
121 enable network stats (receive, send)
122 -N eth1,total
124 include eth1 and total (when using -n/--net)
125 --net-packets
127 show the number of packets received and transmitted
128 -p, --proc
130 enable process stats (runnable, uninterruptible, new)
131 --proc-count
133 show total number of processes
134 -r, --io
136 enable I/O request stats (read, write requests)
137 -s, --swap
139 enable swap stats (used, free)
140 -S swap1,total
142 include swap1 and total (when using -s/--swap)
143 --snooze show time spent between updates in seconds
145 -t, --time
147 enable time/date output (try --time-adv for millisecond preci‐
148 sion)
149 -T, --epoch
151 enable time counter (seconds since epoch, or millisecond preci‐
152 sion from the --epoch-adv plugin)
153 -y, --sys
155 enable system stats (interrupts, context switches)
156 --aio enable aio stats (asynchronous I/O)
158 --cpu-adv
160 enable advanced CPU stats
161 --cpu-use
163 enable only CPU usage stats
164 --disk-avgqu
166 average queue length of the requests that were issued to the de‐
167 vice
168 --disk-avgrq
170 average size (in sectors) of the requests that were issued to
171 the device
172 --disk-svctm
174 average service time (in milliseconds) for I/O requests that
175 were issued to the device
176 --disk-tps
178 number of transfers per second that were issued to the device
179 --disk-util
181 percentage of CPU time during which I/O requests were issued to
182 the device (bandwidth utilization for the device)
183 --disk-wait
185 average time (in milliseconds) for I/O requests issued to the
186 device to be served
187 --fs, --filesystem
189 enable filesystem stats (open files, inodes)
190 --freespace
192 per filesystem used and available space
193 --ipc enable ipc stats (message queue, semaphores, shared memory)
195 --lock enable file lock stats (posix, flock, read, write)
197 --mem-adv
199 enable advanced memory stats
200 --raw enable raw stats (raw sockets)
202 --socket
204 enable socket stats (total, tcp, udp, raw, ip-fragments)
205 --tcp enable tcp stats (listen, established, syn, time_wait, close)
207 --udp enable udp stats (listen, active)
209 --unix enable unix stats (datagram, stream, listen, active)
211 --utmp shows login information from utmp(5)
213 --vm enable virtual memory stats (hard pagefaults, soft pagefaults,
215 allocated, free)
216 --vm-adv
218 enable advance virtual memory stats (steal, scanK, scanD, pgoru,
219 astll)
220 --nfs3 show NFS v3 client operations
222 --nfs3-ops
224 show extended NFS v3 client operations
225 --nfsd3
227 show NFS v3 server operations
228 --nfsd3-ops
230 show extended NFS v3 server operations
231 --nfsd4-ops
233 show extended NFS v4 server operations
234 --nfsstat4
236 show NFS v4 stats
237 --rpc show remote procedure call (RPC) client calls stats
239 --rpcd show remote procedure call (RPC) server calls stats
241 --top-bio
243 show most expensive block I/O process
244 --top-bio-adv
246 show most expensive block I/O process (incl. PID and other
247 stats)
248 --top-childwait
250 show process waiting for child the most
251 --top-cpu
253 show most expensive CPU process
254 --top-cpu-adv
256 show most expensive CPU process (incl. PID and other stats)
257 --top-cputime
259 show process using the most CPU time (in milliseconds)
260 --top-cputime-avg
262 show process with the highest average timeslice (in millisec‐
263 onds)
264 --top-io
266 show most expensive I/O process
267 --top-io-adv
269 show most expensive I/O process (incl. PID and other stats)
270 --top-latency
272 show process with highest total latency (in milliseconds)
273 --top-latency-avg
275 show process with the highest average latency (in milliseconds)
276 --top-mem
278 show process using the most memory
279 --top-oom
281 show process that will be killed by the out-of-memory (OOM)
282 killer the first
283 -f, --full
285 expand -C, -D, -I, -N and -S discovery lists
286 -v, --vmstat
288 equals -pmgdsc -D total
289 --bits force bits for values expressed in bytes
291 --float
293 force float values on screen (mutually exclusive with --integer)
294 --integer
296 force integer values on screen (mutually exclusive with --float)
297 --bw, --blackonwhite
299 change colors for white background terminal
300 --nocolor
302 disable colors
303 --noheaders
305 disable repetitive headers
306 --nomissed
308 disable missed ticks warnings for intermediate samples.
309 --noupdate
311 disable intermediate updates when delay greater than 1.
312 -o file, --output=file
314 write CSV (Comma-Separated Value) format output to a file.
315 -p file, --pidfile=file
317 write the process identifier to a given file.
318
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 --battery
325 remaining battery charge in percentage (needs the Denki PMDA)
326 --gpfs
328 GPFS read/write I/O (needs the GPFS PMDA)
329 --gpfs-ops
331 GPFS filesystem operations (needs the GPFS PMDA)
332 --innodb-buffer
334 show innodb buffer stats (needs the MySQL PMDA)
335 --innodb-io
337 show innodb I/O stats (needs the MySQL PMDA)
338 --innodb-ops
340 show innodb operations counters (needs the MySQL PMDA)
341 --lustre
343 show lustre I/O throughput (needs the Lustre PMDA)
344 --memcache-hits
346 show the number of hits and misses from memcache (needs the Mem‐
347 cached PMDA)
348 --mysql5-cmds
350 show the MySQL5 command stats (needs the MySQL PMDA)
351 --mysql5-conn
353 show the MySQL5 connection stats (needs the MySQL PMDA)
354 --mysql5-innodb
356 show the MySQL5 innodb stats (needs the MySQL PMDA)
357 --mysql5-io
359 show the MySQL5 I/O stats (needs the MySQL PMDA)
360 --mysql5-keys
362 show the MySQL5 keys stats (needs the MySQL PMDA)
363 --mysql-io
365 show the MySQL I/O stats (needs the MySQL PMDA)
366 --mysql-keys
368 show the MySQL keys stats (needs the MySQL PMDA)
369 --postfix
371 show postfix queue sizes (needs the Postfix PMDA)
372 --redis
374 show Redis stats (needs the Redis PMDA)
375 --sendmail
377 show sendmail queue size (needs the Sendmail PMDA)
378 --zfs-arc
380 show ZFS arc stats (needs the ZFS PMDA)
381 --zfs-l2arc
383 show ZFS l2arc stats (needs the ZFS PMDA)
384 --zfs-zil
386 show ZFS zil stats (needs the ZFS PMDA)
387
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 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 --battery-remain
399 battery remaining in hours, minutes (needs an ACPI PMDA)
400 --cpufreq
402 CPU frequency in percentage (needs an ACPI PMDA)
403 --dbus number of dbus connections (needs a python-dbus PMDA)
405 --fan fan speed (needs an ACPI PMDA)
407 --md-status
409 show software raid (MD driver) progress and speed (needs new
410 disk.md metrics)
411 --power
413 show power usage (needs an ACPI PMDA)
414 --qmail
416 show qmail queue sizes (needs qmail)
417 --squid
419 show squid usage statistics (needs a Squid PMDA)
420 --thermal
422 system temperature sensors (needs an ACPI PMDA)
423 --vm-cpu
425 show VMware CPU stats from hypervisor (needs a VMware PMDA)
426 --vm-mem
428 show VMware memory stats from hypervisor (needs a VMware PMDA)
429 --vm-mem-adv
431 show advanced VMware memory stats from hypervisor (needs a
432 VMware PMDA)
433 --vmk-hba
435 show VMware ESX kernel vmhba stats (needs a VMware PMDA)
436 --vmk-int
438 show VMware ESX kernel interrupt stats (needs a VMware PMDA)
439 --vmk-nic
441 show VMware ESX kernel port stats (needs a VMware PMDA)
442 --vz-cpu
444 show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)
445 --vz-io
447 show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)
448 --vz-ubc
450 show OpenVZ user beancounters (needs an OpenVZ PMDA)
451 --wifi wireless link quality and signal to noise ratio (needs Linux
453 PMDA metrics)
454
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 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
467 Using pcp-dstat to relate disk-throughput with network-usage (eth0),
468 total CPU-usage and system counters:
469 $ pcp dstat -dnyc -N eth0 -C total -f 5
471 Using the time plugin together with cpu, net, disk, system, load and
473 proc plugins:
474 $ pcp dstat -tcndylp
476 This is identical to:
478 $ pcp dstat --time --cpu --net --disk --sys --load --proc
480 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 Examine the same metrics live from a remote host:
486 $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10
488
491 $HOME/.pcp/dstat/
492 private per-user configuration files
493 $PCP_SYSCONF_DIR/dstat/
495 system-wide configuration files
496
498 Internal plugins behaviour can be changed through environment vari‐
499 ables.
500 DSTAT_TIMEFMT
502 strftime(3) format string for reporting time (see --time)
503
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 For environment variables affecting PCP tools, see pmGetOptions(3).
512
514 The Dstat utility was initially written by Dag Wieers <dag@wieers.com>.
515 The Dstat homepage is at http://dag.wieers.com/home-made/dstat/.
517 This manpage was initially written by Andrew Pollock <apollock@de‐
519 bian.org> for the Debian GNU/Linux system.
520 The pcp-dstat utility is written and maintained by the PCP developers
522 <pcp@groups.io>.
523 The PCP homepage is at https://pcp.io/.
525
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).
530Performance Co-Pilot PCP PCP-DSTAT(1)