xref: /freebsd/usr.sbin/sa/sa.8 (revision 74bf4e164ba5851606a27d4feff27717452583e5)
1.\"
2.\" Copyright (c) 1994 Christopher G. Demetriou
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. All advertising materials mentioning features or use of this software
14.\"    must display the following acknowledgement:
15.\"      This product includes software developed by Christopher G. Demetriou.
16.\" 3. The name of the author may not be used to endorse or promote products
17.\"    derived from this software without specific prior written permission
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29.\"
30.\" $FreeBSD$
31.\"
32.Dd February 25, 1994
33.Dt SA 8
34.Os
35.Sh NAME
36.Nm sa
37.Nd print system accounting statistics
38.Sh SYNOPSIS
39.Nm
40.Op Fl abcdDfijkKlmnqrstu
41.Op Fl v Ar cutoff
42.Op Ar
43.Sh DESCRIPTION
44The
45.Nm
46utility reports on, cleans up,
47and generally maintains system
48accounting files.
49.Pp
50The
51.Nm
52utility is able to condense the information in
53.Pa /var/account/acct
54into the summary files
55.Pa /var/account/savacct
56and
57.Pa /var/account/usracct ,
58which contain system statistics according
59to command name and login id, respectively.
60This condensation is desirable because on a
61large system,
62.Pa /var/account/acct
63can grow by hundreds of blocks per day.
64The summary files are normally read before
65the accounting file, so that reports include
66all available information.
67.Pp
68If file names are supplied, they are read instead of
69.Pa /var/account/acct .
70After each file is read, if the summary
71files are being updated, an updated summary will
72be saved to disk.
73Only one report is printed,
74after the last file is processed.
75.Pp
76The labels used in the output indicate the following, except
77where otherwise specified by individual options:
78.Bl -tag -width k*sec
79.It Dv avio
80Average number of I/O operations per execution
81.It Dv cp
82Sum of user and system time, in minutes
83.It Dv cpu
84Same as
85.Dv cp
86.It Dv k
87CPU-time averaged core usage, in 1k units
88.It Dv k*sec
89CPU storage integral, in 1k-core seconds
90.It Dv re
91Real time, in minutes
92.It Dv s
93System time, in minutes
94.It Dv tio
95Total number of I/O operations
96.It Dv u
97User time, in minutes
98.El
99.Pp
100The options to
101.Nm
102are:
103.Bl -tag -width Ds
104.It Fl a
105List all command names, including those containing unprintable
106characters and those used only once.
107By default,
108.Nm
109places all names containing unprintable characters and
110those used only once under the name ``***other''.
111.It Fl b
112If printing command statistics, sort output by the sum of user and system
113time divided by number of calls.
114.It Fl c
115In addition to the number of calls and the user, system and real times
116for each command, print their percentage of the total over all commands.
117.It Fl d
118If printing command statistics, sort by the average number of disk
119I/O operations.
120If printing user statistics, print the average number of
121disk I/O operations per user.
122.It Fl D
123If printing command statistics, sort and print by the total number
124of disk I/O operations.
125.It Fl f
126Force no interactive threshold comparison with the
127.Fl v
128option.
129.It Fl i
130Do not read in the summary files.
131.It Fl j
132Instead of the total minutes per category, give seconds per call.
133.It Fl k
134If printing command statistics, sort by the cpu-time average memory
135usage.
136If printing user statistics, print the cpu-time average
137memory usage.
138.It Fl K
139If printing command statistics, print and sort by the cpu-storage integral.
140.It Fl l
141Separate system and user time; normally they are combined.
142.It Fl m
143Print per-user statistics rather than per-command statistics.
144.It Fl n
145Sort by number of calls.
146.It Fl q
147Create no output other than error messages.
148.It Fl r
149Reverse order of sort.
150.It Fl s
151Truncate the accounting files when done and merge their data
152into the summary files.
153.It Fl t
154For each command, report the ratio of real time to the sum
155of user and system cpu times.
156If the cpu time is too small to report, ``*ignore*'' appears in
157this field.
158.It Fl u
159Superseding all other flags, for each entry
160in the accounting file, print the user ID, total seconds of cpu usage,
161total memory usage, number of I/O operations performed, and
162command name.
163.It Fl v Ar cutoff
164For each command used
165.Ar cutoff
166times or fewer, print the command name and await a reply
167from the terminal.
168If the reply begins with ``y'', add
169the command to the category ``**junk**''.
170This flag is
171used to strip garbage from the report.
172.El
173.Pp
174By default, per-command statistics will be printed.
175The number of
176calls, the total elapsed time in minutes, total cpu and user time
177in minutes, average number of I/O operations, and CPU-time
178averaged core usage will be printed.
179If the
180.Fl m
181option is specified, per-user statistics will be printed, including
182the user name, the number of commands invoked, total cpu time used
183(in minutes), total number of I/O operations, and CPU storage integral
184for each user.
185If the
186.Fl u
187option is specified, the uid, user and system time (in seconds),
188CPU storage integral, I/O usage, and command name will be printed
189for each entry in the accounting data file.
190.Pp
191If the
192.Fl u
193flag is specified, all flags other than
194.Fl q
195are ignored.
196If the
197.Fl m
198flag is specified, only the
199.Fl b ,
200.Fl d ,
201.Fl i ,
202.Fl k ,
203.Fl q ,
204and
205.Fl s
206flags are honored.
207.Sh DIAGNOSTICS
208.Ex -std
209.Sh FILES
210.Bl -tag -width /var/account/usracct -compact
211.It Pa /var/account/acct
212raw accounting data file
213.It Pa /var/account/savacct
214per-command accounting summary database
215.It Pa /var/account/usracct
216per-user accounting summary database
217.El
218.Sh SEE ALSO
219.Xr lastcomm 1 ,
220.Xr acct 5 ,
221.Xr ac 8 ,
222.Xr accton 8
223.Sh BUGS
224The number of options to this program is absurd, especially considering
225that there's not much logic behind their lettering.
226.Pp
227The field labels should be more consistent.
228.Pp
229The VM system does not record the CPU storage integral.
230.Sh CAVEATS
231While the behavior of the options in this version of
232.Nm
233was modeled after the original version, there are some intentional
234differences and undoubtedly some unintentional ones as well.
235In
236particular, the
237.Fl q
238option has been added, and the
239.Fl m
240option now understands more options than it used to.
241.Pp
242The formats of the summary files created by this version of
243.Nm
244are very different from the those used by the original version.
245This is not considered a problem, however, because the accounting record
246format has changed as well (since user ids are now 32 bits).
247.Sh AUTHORS
248.An Chris G. Demetriou Aq cgd@postgres.berkeley.edu
249