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 .TP
109 .B "8 802.11b
110 display the signal strength detected by the 802.11b wireless ether card; the value
111 is usually below 50% unless the receiver is in the same room as the transmitter, so
112 a midrange value represents a strong signal.
113 .PD
114 .PP
115 The graphs are plotted with time on the horizontal axis.
116 The vertical axes range from 0 to 1000*sleepsecs, 
117 multiplied by the number of processors on the machine
118 when appropriate.
119 The only exceptions are
120 memory,
121 and swap space,
122 which display fractions of the total available, 
123 system load, which displays a number between 0 and 1000, 
124 idle and intr, which display percentages and the Ethernet error count,
125 which goes from 0 to 10..
126 If the value of the parameter is too large for the visible range, its value is shown
127 in decimal in the upper left corner of the graph.
128 .PP
129 Upper-case options control details of the display.
130 All graphs are affected; there is no mechanism to
131 affect only one graph.
132 .TP
133 .BI -T " sleepsecs
134 Set the number of seconds between samples to
135 .I sleepsecs
136 (default one second).
137 .TP
138 .BI -S " scale
139 Sets a scale factor for the displays.  A value of 2, for example,
140 means that the highest value plotted will be twice as large as the default.
141 .TP
142 .B -L
143 Plot all graphs with logarithmic
144 .I y
145 axes.
146 The graph is plotted so the maximum value that would be displayed on
147 a linear graph is 2/3 of the way up the
148 .I y
149 axis and the total range of the graph is a factor of 1000; thus the
150 .I y
151 origin is 1/100 of the default maximum value and the top of the graph is
152 10 times the default maximum.
153 .TP
154 .B -Y
155 If the display is large enough to show them,
156 place value markers along the
157 .I y
158 axes of the graphs.
159 Since one set of markers serves for all machines across the display,
160 the values in the markers disregard scaling factors due to multiple processors
161 on the machines. On a graph for a multiprocessor,
162 the displayed values will be larger
163 than the markers indicate.
164 The markers appear along the right, and the markers
165 show values appropriate to the rightmost machine; this only
166 matters for graphs such as memory that have machine-specific
167 maxima.
168 .PP
169 Typing `q' or DEL causes
170 .I stats
171 to exit.
172 .PD
173 .SH EXAMPLE
174 Show the load, memory, interrupts, system calls, context switches,
175 and ethernet packets for the local machine,
176 a remote BSD machine
177 .IR daemon ,
178 and
179 a remote Linux machine 
180 .IR tux .
181 .I Auxstats
182 is not in
183 .IR tux 's
184 path, so the full path must be given.
185 .IP
186 .EX
187 stats -lmisce `hostname` daemon \e
188     tux:\*9/bin/auxstats
189 .EE
190 .SH SOURCE
191 .B \*9/src/cmd/draw/stats.c
192 .PP
193 .B \*9/src/cmd/auxstats
194 .SH BUGS
195 The
196 .I auxstats
197 binary needs read access to
198 .B /dev/kmem
199 in order to collect network statistics on non-Linux systems.
200 Typically this can be arranged by setting the
201 .I auxstat
202 binary's
203 group to
204 .B kmem
205 and then turning on its set-gid bit.