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
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
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-
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 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-
90 device 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
98 related 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
167 device
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 -f, --full
243 expand -C, -D, -I, -N and -S discovery lists
244 -v, --vmstat
246 equals -pmgdsc -D total
247 --bits force bits for values expressed in bytes
249 --float
251 force float values on screen (mutually exclusive with --integer)
252 --integer
254 force integer values on screen (mutually exclusive with --float)
255 --bw, --blackonwhite
257 change colors for white background terminal
258 --nocolor
260 disable colors
261 --noheaders
263 disable repetitive headers
264 --noupdate
266 disable intermediate updates when delay greater than 1.
267 -o file, --output=file
269 write CSV (Comma-Separated Value) format output to a file.
270 -p file, --pidfile=file
272 write the process identifier to a given file.
273
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 --gpfs
280 GPFS read/write I/O (needs the GPFS PMDA)
281 --gpfs-ops
283 GPFS filesystem operations (needs the GPFS PMDA)
284 --innodb-buffer
286 show innodb buffer stats (needs the MySQL PMDA)
287 --innodb-io
289 show innodb I/O stats (needs the MySQL PMDA)
290 --innodb-ops
292 show innodb operations counters (needs the MySQL PMDA)
293 --lustre
295 show lustre I/O throughput (needs the Lustre PMDA)
296 --memcache-hits
298 show the number of hits and misses from memcache
299 --mysql5-cmds
301 show the MySQL5 command stats (needs the MySQL PMDA)
302 --mysql5-conn
304 show the MySQL5 connection stats (needs the MySQL PMDA)
305 --mysql5-innodb
307 show the MySQL5 innodb stats (needs the MySQL PMDA)
308 --mysql5-io
310 show the MySQL5 I/O stats (needs the MySQL PMDA)
311 --mysql5-keys
313 show the MySQL5 keys stats (needs the MySQL PMDA)
314 --mysql-io
316 show the MySQL I/O stats (needs the MySQL PMDA)
317 --mysql-keys
319 show the MySQL keys stats (needs the MySQL PMDA)
320 --postfix
322 show postfix queue sizes (needs the Postfix PMDA)
323 --redis
325 show Redis stats (needs the Redis PMDA)
326 --sendmail
328 show sendmail queue size (needs the Sendmail PMDA)
329
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 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 --battery
341 battery in percentage (needs an ACPI PMDA)
342 --battery-remain
344 battery remaining in hours, minutes (needs an ACPI PMDA)
345 --cpufreq
347 CPU frequency in percentage (needs an ACPI PMDA)
348 --dbus
350 number of dbus connections (needs a python-dbus PMDA)
351 --fan
353 fan speed (needs an ACPI PMDA)
354 --md-status
356 show software raid (MD driver) progress and speed (needs new
357 disk.md metrics)
358 --power
360 show power usage (needs an ACPI PMDA)
361 --qmail
363 show qmail queue sizes (needs qmail)
364 --squid
366 show squid usage statistics (needs a Squid PMDA)
367 --thermal
369 system temperature sensors (needs an ACPI PMDA)
370 --vm-cpu
372 show VMware CPU stats from hypervisor (needs a VMware PMDA)
373 --vm-mem
375 show VMware memory stats from hypervisor (needs a VMware PMDA)
376 --vm-mem-adv
378 show advanced VMware memory stats from hypervisor (needs a VMware
379 PMDA)
380 --vmk-hba
382 show VMware ESX kernel vmhba stats (needs a VMware PMDA)
383 --vmk-int
385 show VMware ESX kernel interrupt stats (needs a VMware PMDA)
386 --vmk-nic
388 show VMware ESX kernel port stats (needs a VMware PMDA)
389 --vz-cpu
391 show CPU usage per OpenVZ guest (needs an OpenVZ PMDA)
392 --vz-io
394 show I/O usage per OpenVZ guest (needs an OpenVZ PMDA)
395 --vz-ubc
397 show OpenVZ user beancounters (needs an OpenVZ PMDA)
398 --wifi
400 wireless link quality and signal to noise ratio (needs Linux PMDA
401 metrics)
402 --zfs-arc
404 show ZFS arc stats (needs a Linux ZFS PMDA)
405 --zfs-l2arc
407 show ZFS l2arc stats (needs a Linux ZFS PMDA)
408 --zfs-zil
410 show ZFS zil stats (needs a Linux ZFS PMDA)
411
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 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
424 Using pcp-dstat to relate disk-throughput with network-usage (eth0),
425 total CPU-usage and system counters:
426 $ pcp dstat -dnyc -N eth0 -C total -f 5
428 Using the time plugin together with cpu, net, disk, system, load and
430 proc plugins:
431 $ pcp dstat -tcndylp
433 This is identical to:
435 $ pcp dstat --time --cpu --net --disk --sys --load --proc
437 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 Examine the same metrics live from a remote host:
443 $ pcp --host www.acme.com dstat --time --cpu-adv --sys 1 10
445
448 $HOME/.pcp/dstat/
449 private per-user configuration files
450 $PCP_SYSCONF_DIR/pcp/dstat/
452 system-wide configuration files
453
455 Internal plugins behaviour can be changed through environment vari‐
456 ables.
457 DSTAT_TIMEFMT
459 strftime(3) format string for reporting time (see --time)
460
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 For environment variables affecting PCP tools, see pmGetOptions(3).
469
471 The Dstat utility was initially written by Dag Wieers <dag@wieers.com>.
472 The Dstat homepage is at http://dag.wieers.com/home-made/dstat/.
474 This manpage was initially written by Andrew Pollock <apol‐
476 lock@debian.org> for the Debian GNU/Linux system.
477 The pcp-dstat utility is written and maintained by the PCP developers
479 <pcp@groups.io>.
480 The PCP homepage is at https://pcp.io/.
482
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).
487Performance Co-Pilot PCP PCP-DSTAT(1)