\. %Z%%M% Version:%I% Last Change:%G% .TH STATIT 8 "10 July 1989" .SH NAME statit \- show cpu, memory, network and IO statistics .SH SYNOPSIS statit [ -bhnstxy ] [ -c core_file ] [ -f user_stats_file ] [ -i interval ] [ -k kernel ] [ -o output_file ] [ -u binary_output_file ] [ -v binary_input_file ] [ command ] .SH DESCRIPTION Statit reads and prints kernel resource utilization statistics from the memory or core image of a kernel. It may be used to look at how a program utilizes kernel resources or to print continuously updated statistics about kernel variables. .SH OPTIONS The options are: .IP -b bare mode. Do not print any identifying text. All variables are printed on one line. At present statit has two output modes: the default mode, which prints a two column screenful of statistics and identifying text; and the -b or -h (see below) modes which print raw data without identifying text or just a line of description associated with each variable in the bare mode. Output from the -b mode is in a form suitable for digestion by a post processing program. There are presently some bugs in the bare mode output formatting. .IP "-c \fIcore_file\fR" specify a core file to read instead of the default in memory kernel image \fI/dev/kmem\fR. .IP "-f \fIuser_stats_file\fR" specify a configuration file which contains a list of variables that the user is interested in. The variables must be offsets from a symbol name appearing in the kernel symbol table. For example, the following lines are used to observe the characters input to the tty and the cpu user, nice, system and idle times: .nf \f(CW # TTY statistics _tk_nin 0 long total tty characters input # CPU statistics _cp_time 0 long user time (ticks) _cp_time 4 long nice time (ticks) _cp_time 8 long system time (ticks) _cp_time 12 long idle time (ticks) .fi .IP The format of the file is as follows: words must start at the beginning of a line and use a space as a separator. If the first letter in a line is a pound (#), space or tab, the rest of the line is ignored. The first word in a line must be a valid symbol name. The existence of a symbol can be verified by using the nm(1) command. For example, to check if the symbol _tk_nin occurs in /vmunix one can use the command: .nf example% nm /vmunix | egrep tk_nin .IP If _tk_nin exists in the symbol table you would get an output like this: .nf 0f099868 B _tk_nin .fi .IP The second word in \fIuser_stats_file\fR must be an offset from the symbol specified in the first word. In the above example _cp_time is really the symbol name of an array declared as follows in \fI/usr/include/sys/dk.h\fR: .nf long cp_time[4]; .fi .IP where cp_time[0] contains the user time and cp_time[3] contains cpu idle time. The third word is the C type of the variable you want to read at the specified offset from the given symbol. At present only the types .nf char, double, float, int, long, short and string (max of 7 chars). .fi .IP are supported. The fourth and subsequent words in a line are taken to be description lines and are output when the -fh options are specified. .IP -h header mode - prints a description of each of the bare mode variables. In the header mode the description of each variable is output on a separate line. The description is preceded by the field number of the variable as it appeared in the bare mode. The statit command to output the headers should exactly resemble the associated bare mode command except that the -h option substitutes for the -b option. No commands are executed by statit in the header mode. .IP "-i interval" interval mode - print the difference in kernel variables every interval seconds. Start with a snapshot of the kernel state till now. A \fIcommand\fR may be given with the -i mode, to enable command monitoring. If a \fIcommand\fR is given statit will exit upon printing the next scheduled output after the completion of the command. Note that an interval of less than 3 seconds may cause high cpu overhead. Specifying the -i mode will make output variables appear in bare mode, unless the -u flag (described below) is used. .IP -n Show nfs statistics in the manner of NFSSTAT(8C). .IP "-k \fIkernel\fR" report the statistics of a \fIkernel\fR other than the default \fI/vmunix\fR. .IP "-o \fIoutfile\fR" append statit output to \fIoutfile\fR rather than to the default stdout. .IP -s snapshot mode. Print kernel statistics up to the present time since the last boot. .IP -t Print output as totals rather than the default per second rate. .IP "-u \fIbinary_output_file\fR" Used with the -i flag above to store data in binary form instead of bare mode. This is much more efficient in disk space and CPU overhead. Data can be converted back to ascii form using the -v flag below. .IP "-v \fIbinary_input_file\fR" Converts binary data captured using the -u flag to default ascii mode of presentation. The -u and -v flags may be used together to monitor a system for extended periods. The command .nf statit -ni 10 -u /tmp/binout sleep 3600 .fi .IP This will run the "sleep" command for 1 hour and will take a snapshot of all system statistics (including NFS statistics) every 10 seconds during that hour. The data is saved in binary form in the file /tmp/binout. These statistics can then be converted to standard statit output format by the command .nf statit -nv /tmp/binout .fi .IP -x binary snapshot mode. Store a binary snapshot of the kernel statistics in the file \fI/tmp/Xstat\fR. To be used in conjunction with the -y option below. .IP -y binary snapshot mode. Take a snapshot of kernel statistics. Read a set of previously saved statistics from \fI/tmp/Xstat\fR and then remove it. Compute the difference in the two snapshots and output the result. The -x and -y flags are useful when it is inconvenient to fork a command from statit. In that case the commands to be measured are enclosed between a statit -x and a statit -y. .SH NOTES\ \ \ If a \fIcommand\fR is specified without the interval mode, statit executes the \f(CWWAIT(2)\fR command and thus uses minimal resources while the \fIcommand\fR completes. When a \fIcommand\fR is specified with the \fIinterval\fR mode, statit will snapshot statistics every \fIinterval\fR seconds (starting with an initial snapshot) until the command completes. Note that running statit changes the kernel statistics, and a small interval (< 3 seconds) will cause high overhead. .LP When the following is typed: .nf example% statit -o temp1 ls .fi .LP statit executes the \fIcommand\fR "ls" and outputs the default set of statistics to the file temp1. The output generated by "ls" goes, as usual, to the standard output. The contents of temp1 look like this: .in -0.5i \f(CW .nf Hostid: 5100bbd2 Hostname: "firefly" Version: 2.04 Command: ls Elapsed Time Statistics 1.09 time (seconds) 100.00 % Start time: Thu Mar 14 13:19:08 1991 0.58 user time 53.21 % 0.00 nice time 0.00 % 0.33 system time 30.28 % 0.18 idle time 16.51 % System Statistics (per second) 55.05 cpu context switches 133.94 traps 291.74 system calls 165.14 device interrupts 0.00 swapins 0.00 swapouts 0.00 pages swapped in 0.00 pages swapped out 0.00 page ins 1.83 page outs 0.00 pages paged in 1.83 pages paged out 3.67 page reclaims from free list 112.84 total page faults taken 0.00 intransit blocking pg flts 3.67 totl pg reclms (includes pgout) 0.00 swap txt pgs fnd on free lst 3.67 inode txt pgs fnd in free lst 82.57 pgs xmnd by the clock daemon 0.00 revs of the clock hand 19.27 pgs zero filled on demand 31.19 pages freed by clock daemon Hat Statistics (per second) 2.75 ctxt allocations 1.83 ctxts stolen from other as's 133.94 pmg_allocs that have pmg 12.84 pmg allocations 0.00 pmgs stoln frm as's w/no ctx 0.00 pmgs stoln frm as's with ctx 0.00 smg_allocs that have smg 0.00 smg allocations 0.00 smgs stoln frm proc w/no ctx 0.00 smgs stoln frm proc with ctx 3.67 pmgs found on as at ctx_alloc Virt Addr Cache Flush Statistics (per second) 1.83 context flushes 0.00 segment flushes 207.34 complete page flushes 0.00 partial page flushes 0.00 non-supervisor flushes 0.00 region flushes Directory Name Cache Statistics (per second) 18.35 cache hits ( 83 %) 3.67 cache misses ( 16 %) 1.83 enters into cache 0.00 enters when already cached 0.00 long names tried to enter 0.00 long names tried to look up 0.00 LRU list empty 0.00 purges of cache Buffer Cache Statistics (per second) 37.61 total bread requests 37.61 bread hits ( 100 %) 0.00 times aged buf was alloced 0.00 times lru buf was alloced 0.00 times had to sleep for buf TTY Statistics 0.00 ttyin/sec 4389.91 ttyout/sec Device: sd0 6.42 % time disk busy 15031.19 bytes/sec 5.02 % time disk seeking 2.75 disk transfers/sec 0.00 disk reads/sec 0.00 seeks/sec Device: sd1 1.83 % time disk busy 3757.80 bytes/sec 1.49 % time disk seeking 0.92 disk transfers/sec 0.00 disk reads/sec 0.00 seeks/sec Device: sd3 3.67 % time disk busy 18788.99 bytes/sec 1.92 % time disk seeking 2.75 disk transfers/sec 0.00 disk reads/sec 0.00 seeks/sec Interface: le0 19.27 input packets/sec 0.00 input errors/sec 7.34 output packets/sec 0.00 output errors/sec 0.00 collisions/sec Interface: lo0 1.83 input packets/sec 0.00 input errors/sec 1.83 output packets/sec 0.00 output errors/sec 0.00 collisions/sec Rusage Statistics 0.23 user time 0.22 system time 66 max resident set size (pgs) 0 integral shared text size 2334 integral unshared data size 0 integral unshared stack size 94 page reclaims (no IO) 0 page faults (required IO) 0 swaps 0 block input operations 0 block output operations 0 messages sent over sockets 0 messages recvd from sockets 0 signals received 9 voluntary context switches 0 involuntary context switches .in +0.5i \fR .fi .LP Most of the output of statit shown above should be self explanatory. Refer to a Unix architecture book such as "BSD 4.2 Unix" by Leffler, McKusik, et. al. for detailed explanations of the meanings of most of these statistics or look at SunOS source. Interface: le0 refers to the lance ethernet interface # 0 on the machine. Device: sd0 refers to a SCSI drive, and the statistics that pertain to it. The Rusage statistics are derived from the \fIgetrusage\fR (2) system call. \fIgetrusage\fR (2) returns statistics pertaining to all the child processes (commands) spawned by statit. Therefore Rusage Statistics may differ slightly from the statistics above them because the latter include the overhead of forking off the commands. The block IO statistics reported by \fIgetrusage\fR (2) refer to the number of complete 8K byte blocks input or output from the file system. In this respect the block statistics are different from the Device statistics which report only raw IO numbers. .LP In the following example: .nf example% statit -bo temp2 ls .fi .IP the bare mode output of statit is output in a single line and stored in temp2. The bare mode output consists of approximately 90 (the exact number depends on the command and machine configuration) numbers and words. The first few numbers output by statit look like this: .in -0.5i \f(CW .nf 590797572.76 50 19 0 13 ... .in +0.5i .fi .IP To make sense of the bare mode numbers it is necessary to use the header mode as follows: .nf example% statit -ho temp3 ls .fi .IP Part of the output is shown below. Each statistic is printed one to a line with a field number followed by a short description. .in -0.5i \f(CW .nf 1 start time (seconds) 2 hertz (ticks/sec) 3 user time (ticks) 4 nice time (ticks) 5 system time (ticks) 6 idle time (ticks) 7 Sum_Statistics Header 8 cpu context switches 9 traps 10 system calls 11 device interrupts 12 pseudo dma interrupts VAX only . . . 81 output packets 82 output errors 83 collisions 84 Hostid Header 85 Hostid 86 Hostname Header 87 Hostname 88 Version Header 89 Version Number 90 Command Header .fi .in +0.5i .SH AUTHOR .nf Varun Mehta varun@firefly.Eng.Sun.com Sun Microsystems, Inc. .SH FILES .nf /vmunix default kernel object file. /dev/kmem kernel memory. /tmp/Xstat temporary statistics stored in binary form (-x option only) .fi .SH "BUGS " There are presently some bugs in the -b and -h modes, I suggest that they not be used at present. .LP In cases where the program being measured is very short (under 3 seconds) or statit is called with a short interval its output may not be accurate. For example, the statistics that relate to virtual memory are updated once every second. Statit would thus show a large number of zero statistics for programs that take less than a second to run. Statit causes some overhead of its own, and in short benchmarks these can be appreciable. .LP Note that statit output can be misleading due to other reasons. In many cases kernel or device driver implementations fail to update statistics that statit reads. Using commands like \fIvmstat(8)\fR or \fIiostat(8)\fR to verify the performance of statit may not be useful since statit employs the same mechanism as the latter commands. Other ways can be devised to verify certain statistics. For example, the characters input to or output from ttys can easily be counted. To verify certain disk statistics use a command such as .nf statit -o temp dd if=/dev/rsd0a of=/dev/null bs=128w count=100 .fi .LP In this case the \fIdd(1)\fR command will read a 100 blocks of size 512 bytes from the raw I/O device sd0. The output of statit can be checked to see that a 100 reads were done on sd0 and that 51200 bytes of data were transferred. Similarly the \fIspray(8C)\fR command can be used to verify ethernet interface statistics by including it in a command such as .nf statit -o temp spray remote_host -c 1000 -l 1024 .fi .LP This command will send a 1000 packets of length 1024 bytes from your host to the remote_host. Note that statit will report a lower average packet throughput than \fIspray(8C)\fR because statit measures the extra overhead of forking off \fIspray(8C)\fR. .LP To verify statistics concerning page and swap rates is a little harder. The onset of swapping, for example, depends on a number of factors such as the number of contexts available in the MMU and the number of free pages in physical memory. A program that does rapid context switching between a large number of processes would be a good candidate to see if the context switching and process swapping statistics behave as expected. .LP Please report all bugs/suggestions to Varun Mehta (varun@firefly). .fi .SH "SEE ALSO" vmstat(8), iostat(8), netstat(8), nfsstat(8C), pstat(8), getrusage(2)