1 .TH STATS 1
2 .SH NAME
3 stats, auxstats \- display graphs of system activity
4 .SH SYNOPSIS
5 .B stats
6 [
7 .BI - option
8 ]
9 [
10 .IB machine\fR[ : path\fR]
11 \&...
12 ]
13 .PP
14 .B auxstats
15 [
16 .I machine
17 [
18 .I path
19 ] ]
20 .SH DESCRIPTION
21 .I Stats
22 displays a rolling graph of various statistics collected by the operating
23 system and updated once per second.
24 The statistics may be from a remote
25 .I machine
26 or multiple
27 .IR machines ,
28 whose graphs will appear in adjacent columns.
29 The columns are labeled by the machine names and the number
30 of processors on the machine if it is a multiprocessor.
31 .PP
32 .I Auxstats
33 collects the machine statistics for display by
34 .IR stats .
35 With no arguments, it collects statistics from the local machine.
36 If
37 .I machine
38 is named, it executes
39 .B ssh
40 .I machine
41 .IR path ;
42 when
43 .I ssh
44 finishes, 
45 .I auxstats
46 sleeps for one minute and runs it again.
47 The default
48 .I path
49 is simply
50 .BR auxstats ,
51 but since some shells do not execute any sort of user profile
52 when run as a non-login shell, it is often necessary to specify
53 an exact path.
54 .PP
55 The right mouse button presents a menu to enable and disable the display
56 of various statistics; by default,
57 .I stats
58 begins by showing the load average on the executing machine.
59 .PP
60 The
61 lower-case
62 .I options
63 choose the initial set to display:
64 .TF [t]tlbpurge
65 .TP
66 .B "b battery
67 percentage battery life remaining.
68 .TP
69 .B "c context
70 number of process context switches per second.
71 .TP
72 .B 
73 .B "e ether
74 total number of packets sent and received per second.
75 .TP
76 .B 
77 .B "E etherin,out
78 number of packets sent and received per second, displayed as separate graphs.
79 .TP
80 .B "f fault
81 number of page faults per second.
82 .TP
83 .B "i intr
84 number of interrupts per second.
85 .TP
86 .B "l load
87 (default) system load average.
88 The load is computed as a running average of
89 the number of processes ready to run, multiplied by 1000.
90 On most systems, it changes only every five seconds and has limited accuracy.
91 .TP
92 .B "m mem 
93 total pages of active memory.
94 The graph displays the fraction
95 of the machine's total memory in use.
96 .TP
97 .B 
98 .B "n etherin,out,err
99 number of packets sent and received per second, and total number of errors, displayed as separate graphs.
100 .TP
101 .B "s syscall
102 number of system calls per second.
103 .TP
104 .B "w swap
105 number of valid pages on the swap device.
106 The swap is displayed as a
107 fraction of the number of swap pages configured by the machine.
108 .PD
109 .PP
110 The graphs are plotted with time on the horizontal axis.
111 The vertical axes range from 0 to 1000*sleepsecs, 
112 multiplied by the number of processors on the machine
113 when appropriate.
114 The only exceptions are
115 memory,
116 and swap space,
117 which display fractions of the total available, 
118 system load, which displays a number between 0 and 1000, 
119 idle and intr, which display percentages and the Ethernet error count,
120 which goes from 0 to 10..
121 If the value of the parameter is too large for the visible range, its value is shown
122 in decimal in the upper left corner of the graph.
123 .PP
124 Upper-case options control details of the display.
125 All graphs are affected; there is no mechanism to
126 affect only one graph.
127 .TP
128 .BI -T " sleepsecs
129 Set the number of seconds between samples to
130 .I sleepsecs
131 (default one second).
132 .TP
133 .BI -S " scale
134 Sets a scale factor for the displays.  A value of 2, for example,
135 means that the highest value plotted will be twice as large as the default.
136 .TP
137 .B -L
138 Plot all graphs with logarithmic
139 .I y
140 axes.
141 The graph is plotted so the maximum value that would be displayed on
142 a linear graph is 2/3 of the way up the
143 .I y
144 axis and the total range of the graph is a factor of 1000; thus the
145 .I y
146 origin is 1/100 of the default maximum value and the top of the graph is
147 10 times the default maximum.
148 .TP
149 .B -Y
150 If the display is large enough to show them,
151 place value markers along the
152 .I y
153 axes of the graphs.
154 Since one set of markers serves for all machines across the display,
155 the values in the markers disregard scaling factors due to multiple processors
156 on the machines. On a graph for a multiprocessor,
157 the displayed values will be larger
158 than the markers indicate.
159 The markers appear along the right, and the markers
160 show values appropriate to the rightmost machine; this only
161 matters for graphs such as memory that have machine-specific
162 maxima.
163 .PP
164 Typing `q' or DEL causes
165 .I stats
166 to exit.
167 .PD
168 .SH EXAMPLE
169 Show the load, memory, interrupts, system calls, context switches,
170 and ethernet packets for the local machine,
171 a remote BSD machine
172 .IR daemon ,
173 and
174 a remote Linux machine 
175 .IR tux .
176 .I Auxstats
177 is not in
178 .IR tux 's
179 path, so the full path must be given.
180 .IP
181 .EX
182 stats -lmisce `hostname` daemon \e
183     tux:\*9/bin/auxstats
184 .EE
185 .SH SOURCE
186 .B \*9/src/cmd/draw/stats.c
187 .PP
188 .B \*9/src/cmd/auxstats
189 .SH BUGS
190 The
191 .I auxstats
192 binary needs read access to
193 .B /dev/kmem
194 in order to collect network statistics on non-Linux systems.
195 Typically this can be arranged by setting the
196 .I auxstat
197 binary's
198 group to
199 .B kmem
200 and then turning on its set-gid bit.