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 [dstat options] [delay [count]]
10
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 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 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 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 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 The list of all available plugins can be seen using the --list dstat
43 command line option.
44
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 The available dstat options are:
51 --list list all available plugin names
53 --plugin-name
55 enable any plugin by name
56 -a, --all
58 equals -cdngy (default plugin set)
59 -c, --cpu
61 enable CPU stats (system, user, idle, wait), for more CPU related
62 stats also see --cpu-adv and --cpu-use
63 -C 0,3,total
65 include CPU0, CPU3 and total (when using -c/--cpu); use all to
66 show all CPUs
67 -d, --disk
69 enable disk stats (read, write), for more disk related stats look
70 into the other --disk plugins
71 -D total,hda
73 include total and hda (when using -d/--disk)
74 -g, --page
76 enable page stats (page in, page out)
77 -i, --int
79 enable interrupt stats
80 -I 5,10
82 include interrupt 5 and 10 (when using -i/--int)
83 -l, --load
85 enable load average stats (1 min, 5 mins, 15 mins)
86 -m, --mem
88 enable memory stats (used, buffers, cache, free); for more memory
89 related stats also try --mem-adv and --swap
90 -n, --net
92 enable network stats (receive, send)
93 -N eth1,total
95 include eth1 and total (when using -n/--net)
96 --net-packets
98 show the number of packets received and transmitted
99 -p, --proc
101 enable process stats (runnable, uninterruptible, new)
102 --proc-count
104 show total number of processes
105 -r, --io
107 enable I/O request stats (read, write requests)
108 -s, --swap
110 enable swap stats (used, free)
111 -S swap1,total
113 include swap1 and total (when using -s/--swap)
114 --snooze show time spent between updates in seconds
116 -t, --time
118 enable time/date output (try --time-adv for millisecond preci‐
119 sion)
120 -T, --epoch
122 enable time counter (seconds since epoch, or millisecond preci‐
123 sion from the --epoch-adv plugin)
124 -y, --sys
126 enable system stats (interrupts, context switches)
127 --aio enable aio stats (asynchronous I/O)
129 --cpu-adv
131 enable advanced CPU stats
132 --cpu-use
134 enable only CPU usage stats
135 --disk-avgqu
137 average queue length of the requests that were issued to the
138 device
139 --disk-avgrq
141 average size (in sectors) of the requests that were issued to
142 the device
143 --disk-svctm
145 average service time (in milliseconds) for I/O requests that
146 were issued to the device
147 --disk-tps
149 number of transfers per second that were issued to the device
150 --disk-util
152 percentage of CPU time during which I/O requests were issued to
153 the device (bandwidth utilization for the device)
154 --disk-wait
156 average time (in milliseconds) for I/O requests issued to the
157 device to be served
158 --fs, --filesystem
160 enable filesystem stats (open files, inodes)
161 --freespace
163 per filesystem used and available space
164 --ipc enable ipc stats (message queue, semaphores, shared memory)
166 --lock enable file lock stats (posix, flock, read, write)
168 --mem-adv
170 enable advanced memory stats
171 --raw enable raw stats (raw sockets)
173 --socket
175 enable socket stats (total, tcp, udp, raw, ip-fragments)
176 --tcp enable tcp stats (listen, established, syn, time_wait, close)
178 --udp enable udp stats (listen, active)
180 --unix enable unix stats (datagram, stream, listen, active)
182 --utmp shows login information from utmp(5)
184 --vm enable virtual memory stats (hard pagefaults, soft pagefaults,
186 allocated, free)
187 --vm-adv
189 enable advance virtual memory stats (steal, scanK, scanD, pgoru,
190 astll)
191 --nfs3 show NFS v3 client operations
193 --nfs3-ops
195 show extended NFS v3 client operations
196 --nfsd3
198 show NFS v3 server operations
199 --nfsd3-ops
201 show extended NFS v3 server operations
202 --nfsd4-ops
204 show extended NFS v4 server operations
205 --nfsstat4
207 show NFS v4 stats
208 --rpc show remote procedure call (RPC) client calls stats
210 --rpcd show remote procedure call (RPC) server calls stats
212 --top-bio
214 show most expensive block I/O process
215 --top-bio-adv
217 show most expensive block I/O process (incl. PID and other
218 stats)
219 --top-childwait
221 show process waiting for child the most
222 --top-cpu
224 show most expensive CPU process
225 --top-cpu-adv
227 show most expensive CPU process (incl. PID and other stats)
228 --top-cputime
230 show process using the most CPU time (in milliseconds)
231 --top-cputime-avg
233 show process with the highest average timeslice (in millisec‐
234 onds)
235 --top-int
237 show most frequent interrupt
238 --top-io
240 show most expensive I/O process
241 --top-io-adv
243 show most expensive I/O process (incl. PID and other stats)
244 --top-latency
246 show process with highest total latency (in milliseconds)
247 --top-latency-avg
249 show process with the highest average latency (in milliseconds)
250 --top-mem
252 show process using the most memory
253 --top-oom
255 show process that will be killed by the out-of-memory (OOM)
256 killer the first
257 -f, --full
259 expand -C, -D, -I, -N and -S discovery lists
260 -v, --vmstat
262 equals -pmgdsc -D total
263 --bits force bits for values expressed in bytes
265 --float
267 force float values on screen (mutually exclusive with --integer)
268 --integer
270 force integer values on screen (mutually exclusive with --float)
271 --bw, --blackonwhite
273 change colors for white background terminal
274 --nocolor
276 disable colors
277 --noheaders
279 disable repetitive headers
280 --noupdate
282 disable intermediate updates when delay greater than 1.
283 -o file, --output file
285 write CSV (Comma-Separated Value) format output to a file.
286
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 --innodb-buffer
293 show innodb buffer stats (needs the MySQL PMDA)
294 --innodb-io
296 show innodb I/O stats (needs the MySQL PMDA)
297 --innodb-ops
299 show innodb operations counters (needs the MySQL PMDA)
300 --lustre
302 show lustre I/O throughput (needs the Lustre PMDA)
303 --memcache-hits
305 show the number of hits and misses from memcache
306 --mysql5-cmds
308 show the MySQL5 command stats (needs the MySQL PMDA)
309 --mysql5-conn
311 show the MySQL5 connection stats (needs the MySQL PMDA)
312 --mysql5-innodb
314 show the MySQL5 innodb stats (needs the MySQL PMDA)
315 --mysql5-io
317 show the MySQL5 I/O stats (needs the MySQL PMDA)
318 --mysql5-keys
320 show the MySQL5 keys stats (needs the MySQL PMDA)
321 --mysql-io
323 show the MySQL I/O stats (needs the MySQL PMDA)
324 --mysql-keys
326 show the MySQL keys stats (needs the MySQL PMDA)
327 --postfix
329 show postfix queue sizes (needs the Postfix PMDA)
330 --redis
332 show Redis stats (needs the Redis PMDA)
333 --sendmail
335 show sendmail queue size (needs the Sendmail PMDA)
336
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 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 --battery
348 battery in percentage (needs an ACPI PMDA)
349 --battery-remain
351 battery remaining in hours, minutes (needs an ACPI PMDA)
352 --cpufreq
354 CPU frequency in percentage (needs an ACPI PMDA)
355 --dbus
357 number of dbus connections (needs a python-dbus PMDA)
358 --fan
360 fan speed (needs an ACPI PMDA)
361 --gpfs
363 GPFS read/write I/O (needs mmpmon and a GPFS PMDA)
364 --gpfs-ops
366 GPFS filesystem operations (needs mmpmon and a GPFS PMDA)
367 --md-status
369 show software raid (MD driver) progress and speed (needs new
370 disk.md metrics)
371 --power
373 show power usage (needs an ACPI PMDA)
374 --qmail
376 show qmail queue sizes (needs qmail)
377 --squid
379 show squid usage statistics (needs a Squid PMDA)
380 --thermal
382 system temperature sensors (needs an ACPI PMDA)
383 --vm-cpu
385 show VMware CPU stats from hypervisor (needs a VMware PMDA)
386 --vm-mem
388 show VMware memory stats from hypervisor (needs a VMware PMDA)
389 --vm-mem-adv
391 show advanced VMware memory stats from hypervisor (needs a VMware
392 PMDA)
393 --vmk-hba
395 show VMware ESX kernel vmhba stats (needs a VMware PMDA)
396 --vmk-int
398 show VMware ESX kernel interrupt stats (needs a VMware PMDA)
399 --vmk-nic
401 show VMware ESX kernel port stats (needs a VMware PMDA)
402 --vz-cpu
404 show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)
405 --vz-io
407 show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)
408 --vz-ubc
410 show OpenVZ user beancounters (needs an OpenVZ PMDA)
411 --wifi
413 wireless link quality and signal to noise ratio (needs Linux PMDA
414 metrics)
415 --zfs-arc
417 show ZFS arc stats (needs a Linux ZFS PMDA)
418 --zfs-l2arc
420 show ZFS l2arc stats (needs a Linux ZFS PMDA)
421 --zfs-zil
423 show ZFS zil stats (needs a Linux ZFS PMDA)
424
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 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
437 Using pcp-dstat to relate disk-throughput with network-usage (eth0),
438 total CPU-usage and system counters:
439 $ pcp dstat -dnyc -N eth0 -C total -f 5
441 Using the time plugin together with cpu, net, disk, system, load and
443 proc plugins:
444 $ pcp dstat -tcndylp
446 This is identical to:
448 $ pcp dstat --time --cpu --net --disk --sys --load --proc
450 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 Examine the same metrics live from a remote host:
456 $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10
458
461 $HOME/.pcp/dstat/
462 private per-user configuration files
463 $PCP_SYSCONF_DIR/pcp/dstat/
465 system-wide configuration files
466
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 For environment variables affecting PCP tools, see pmGetOptions(3).
475
477 Internal plugins behaviour can be changed through environment vari‐
478 ables.
479 DSTAT_TIMEFMT
481 strftime(3) format string for reporting time (see --time)
482
484 The Dstat utility was initially written by Dag Wieers <dag@wieers.com>.
485 The Dstat homepage is at http://dag.wieers.com/home-made/dstat/.
487 This manpage was initially written by Andrew Pollock <apol‐
489 lock@debian.org> for the Debian GNU/Linux system.
490 The pcp-dstat utility is written and maintained by the PCP developers
492 <pcp@groups.io>.
493 The PCP homepage is at https://pcp.io/.
495
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).
500Performance Co-Pilot PCP PCP-DSTAT(1)