I'm pleased to sponsor the following fast-track for Chad Mynhier.
Chad is enhancing some of the various "stat" commands to support
a time stamp option in keeping with a similar option provided by
iostat(1m). This case also defines a uniform specification for
this option which future cases can reference in order to add
timestamp options to other "stat" commands.
For those who use the *stat commands to do monitoring over long
periods of time, this will be a welcome addition.
Please ensure that you CC Chad on all correspondance.
-dp
---------------------------------------------------------------------------
Time stamp option for xxstat commands
Chad Mynhier <cmynhier at gmail.com>
SUMMARY
This fast-track enhances the mpstat(1M), vmstat(1M), and
prstat(1M) commands to address an existing RFE[1] requesting an
option for each of these commands to emit a time stamp. In
addition, this fast-track enhances the existing time stamp
functionality in iostat(1M) to print a locale-specific time
stamp, if the standard date format is requested.
This fast-track also sets a precedent that all "*stat" commands
that print statistics at a regular interval should implement a
timestamp feature similar to the one described here.
DETAILS
Overview
Currently, the iostat(1M) and fsstat(1M) commands provide an
option to print a time stamp in either standard date format or
traditional Unix time for each set of data. For example:
# iostat -T d 1
Sat Jan 24 12:34:34 2009
tty sd0 sd1 sd2 cpu
tin tout kps tps serv kps tps serv kps tps serv us sy wt id
0 8 39 1 24 39 1 22 0 0 0 1 1 0 98
Sat Jan 24 12:34:35 2009
0 220 0 0 0 0 0 0 0 0 0 0 1 0 99
Sat Jan 24 12:34:36 2009
0 92 0 0 0 0 0 0 0 0 0 0 1 0 99
^C#
#
# fsstat -T u tmpfs 1
new name name attr attr lookup rddir read read write write
file remov chng get set ops ops ops bytes ops bytes
2.57M 1.63M 25.9K 36.3M 70.8K 26.1M 4.67K 118M 464G 65.8M 253G tmpfs
1232818548
0 0 0 0 0 0 0 0 0 0 0 tmpfs
1232818549
0 0 0 0 0 0 0 0 0 0 0 tmpfs
1232818550
0 0 0 0 0 0 0 0 0 0 0 tmpfs
^C#
The mpstat(1M), vmstat(1M), and prstat(1M) commands do not
provide such an option. This option is useful when gathering
data to correlate with a transient system or application
problem whose time is known after the fact. While this problem
can be worked around by wrapping the command in a script that
adds a time stamp to the output, it would be better to provide
consistency with iostat(1M) and fsstat(1M).
Additionally, the time stamp currently emitted by iostat(1M) is
printed unconditionally in the format specified by the C
locale. For example:
# locale
LANG=
LC_CTYPE="C"
LC_NUMERIC="C"
LC_TIME=fr
LC_COLLATE="C"
LC_MONETARY="C"
LC_MESSAGES="C"
LC_ALL=
# iostat -T d 3
Mon Jan 26 12:03:42 2009
tty sd0 sd1 sd2 cpu
tin tout kps tps serv kps tps serv kps tps serv us sy wt id
0 8 43 1 24 43 1 22 0 0 0 1 1 0 98
Mon Jan 26 12:03:45 2009
0 73 0 0 0 0 0 0 0 0 0 0 0 0 99
^C#
We plan to address these issues as follows:
1. We will add the "[-T d | u]" option to vmstat(1M) and mpstat(1M)
to mirror that option in iostat(1M) and fsstat(1M).
2. We will add the the "[-d d | u]" option to prstat(1M) to print a
time stamp.
3. We will modify iostat(1M) to print the time stamp in a
locale-specific format (i.e., printing local time using
strftime(3C) with the correct format string for the locale.)
There are two possible options for the placement of the
time stamp in the output. The first option is to emit the
time stamp on a separate line prior to each set of data. The
second option is to print the time stamp as an additional column
in the output. We choose the first option for two reasons.
The first of these is that there is a precedent in how
iostat(1M) and fsstat(1M) output the time stamp, as shown
above. The second is that the time stamp would consume a large
number of columns, and these utilities are designed (for the
most part) to fit in 80 columns.
Because the output of mpstat(1M) and prstat(1M) typically
includes multiple rows, we also have the option of printing one
time stamp per row. We choose instead to print one time stamp
per sampling period. This follows the precedent set by
iostat(1M), and it allows the most data to be printed on a
single screen. Note that this also applies to those modes of
prstat(1M) that involve printing two separate sets of data,
such as per-process and per-zone statistics. Only one
time stamp is shown in these cases.
It could be argued that the time stamp option only makes sense
in conjunction with the "-c" option of prstat(1M), given that
otherwise the time stamp is overwritten with each sample. For
the sake of completeness, however, we propose implementing the
time stamp option as an independent option that can be used in
either mode.
EXAMPLE
This example shows mpstat(1M) output using a standard date
format time stamp:
# ./mpstat -T d 1
Sat Jan 24 13:14:59 2009
CPU minf mjf xcal intr ithr csw icsw migr smtx srw syscl usr sys wt idl
0 201 0 77 2219 127 87 3 2 14 1 241 1 1 0 98
1 209 0 73 173 26 92 3 2 15 1 246 1 1 0 98
2 203 0 105 165 24 94 2 2 14 1 240 1 1 0 98
3 207 0 73 177 25 97 3 2 14 1 243 1 1 0 98
Sat Jan 24 13:15:00 2009
CPU minf mjf xcal intr ithr csw icsw migr smtx srw syscl usr sys wt idl
0 18387 0 3246 10899 111 455 222 82 518 79 17262 71 29 0 0
1 24517 0 3635 8790 9 482 210 66 624 86 22727 63 37 0 0
2 20614 0 8964 7016 75 460 189 68 573 83 17889 61 39 0 0
3 23650 0 13319 5535 21 442 186 69 546 75 17211 64 36 0 0
Sat Jan 24 13:15:01 2009
CPU minf mjf xcal intr ithr csw icsw migr smtx srw syscl usr sys wt idl
0 21763 0 4950 13096 130 491 187 89 521 46 15574 62 38 0 0
1 19702 0 12835 8601 48 478 219 86 482 76 16697 64 36 0 0
2 16842 0 11385 9045 62 396 195 69 418 62 14106 74 26 0 0
3 29149 0 8459 10058 18 538 216 85 665 103 24843 55 45 0 0
Sat Jan 24 13:15:02 2009
CPU minf mjf xcal intr ithr csw icsw migr smtx srw syscl usr sys wt idl
0 27958 0 10245 21765 125 657 212 127 817 144 21165 46 52 0 3
1 26394 0 8131 20657 28 703 196 118 847 142 19734 45 52 0 3
2 26998 0 44518 8242 114 478 174 106 778 100 17544 38 61 0 1
3 16175 0 4904 20502 33 553 140 115 506 55 14710 54 38 0 8
^C#
This example shows vmstat(1M) output using a traditional Unix
time stamp:
# ./vmstat -T u 1
kthr memory page disk faults cpu
r b w swap free re mf pi po fr de sr f0 s0 s1 s2 in sy cs us sy id
1232820946
0 0 0 3666444 2642924 59 824 0 0 0 0 4 0 1 1 -1 2735 974 370 1 1 98
1232820947
5 0 0 2521192 1540320 5071 92284 0 0 0 0 0 0 22 20 0 54794 83465 1661 63 37 0
1232820948
4 0 0 2495436 1511176 5642 87339 0 0 0 0 0 0 28 28 0 39021 59198 1570 67 33 0
1232820949
3 0 0 2525936 1545120 5767 81687 0 0 0 0 0 0 20 20 0 31799 60757 1697 69 31 0
^C#
This example shows prstat(1M) output using a standard date
format time stamp (with the -c option):
# amd64/prstat -c -d d -n 5 1
Sat Jan 24 13:17:42 2009
PID USERNAME SIZE RSS STATE PRI NICE TIME CPU PROCESS/NLWP
6920 mynhier 5760K 4664K sleep 0 4 0:00:00 0.5% dmake/1
13928 mynhier 25M 24M sleep 0 4 0:00:00 0.3% dmake/1
9229 mynhier 21M 17M cpu3 0 4 0:00:00 0.3% dmake/1
1504 noaccess 101M 76M sleep 59 0 0:43:09 0.0% java/18
9315 root 3772K 2568K cpu1 39 0 0:00:00 0.0% prstat/1
Total: 95 processes, 256 lwps, load averages: 6.93, 4.99, 2.46
Sat Jan 24 13:17:43 2009
PID USERNAME SIZE RSS STATE PRI NICE TIME CPU PROCESS/NLWP
6920 mynhier 5840K 4748K sleep 0 4 0:00:00 0.5% dmake/1
9229 mynhier 22M 21M sleep 38 4 0:00:00 0.4% dmake/1
9528 mynhier 15M 12M run 0 4 0:00:00 0.4% acomp/1
9430 mynhier 10M 9628K sleep 0 4 0:00:00 0.4% dmake/1
13928 mynhier 25M 24M sleep 38 4 0:00:00 0.3% dmake/1
Total: 114 processes, 274 lwps, load averages: 6.91, 4.99, 2.47
#
This example shows a screenshot of the above command without
the -c option. (There's little difference to be seen between
the previous example and this one, but this one is included in
order to explicitly show the placement of the time stamp in
this mode.):
Sat Jan 24 13:20:25 2009
PID USERNAME SIZE RSS STATE PRI NICE TIME CPU PROCESS/NLWP
4992 mynhier 29M 26M cpu2 0 4 0:00:00 1.1% ube/1
537 mynhier 13M 12M sleep 39 4 0:00:01 1.1% dmake/1
5045 mynhier 45M 41M run 0 4 0:00:00 0.4% ube/1
5145 mynhier 21M 12M run 0 4 0:00:00 0.1% iropt/1
386 mynhier 30M 29M sleep 47 4 0:00:00 0.1% dmake/1
Total: 144 processes, 302 lwps, load averages: 6.76, 5.72, 3.17
This example shows iostat(1M) output using the French locale:
# ./iostat -T d 3
lundi 26 janvier 2009 12 h 08 EST
tty sd0 sd1 sd2 cpu
tin tout kps tps serv kps tps serv kps tps serv us sy wt id
0 8 43 1 24 43 1 22 0 0 0 1 1 0 98
lundi 26 janvier 2009 12 h 08 EST
0 76 0 0 0 0 0 0 0 0 0 0 0 0 100
^C#
DOCUMENTATION
This fast-track proposes adding the following text to the man
pages for mpstat(1M), vmstat(1M), and prstat(1M), with the
exception that the prstat(1M) shall be listed as "-d":
-T u | d
Emit a time stamp.
Specify u for a printed representation of the internal
representation of time. See time(2). Specify d for
standard date format. See date(1).
Additionally, the option should be added to the SYNOPSIS
section of the man pages for each of these.
(The iostat(1M) man page should be changed to read, "See
date(1)." rather than "See ctime(3C)." to reflect the
localization change.)
REFERENCES
[1] would like a timestamp option like iostat has added to mpstat, vmstat
and prstat
(http://bugs.opensolaris.org/view_bug.do?bug_id=4775687)
---------------------------------------------------------------------------
--
Daniel Price, Solaris Kernel Engineering http://blogs.sun.com/dp
