usr.sbin/sa/sa.8

   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
  44 The
  45 .Nm
  46 utility reports on, cleans up,
  47 and generally maintains system
  48 accounting files.
  49 .Pp
  50 The
  51 .Nm
  52 utility is able to condense the information in
  53 .Pa /var/account/acct
  54 into the summary files
  55 .Pa /var/account/savacct
  56 and
  57 .Pa /var/account/usracct ,
  58 which contain system statistics according
  59 to command name and login id, respectively.
  60 This condensation is desirable because on a
  61 large system,
  62 .Pa /var/account/acct
  63 can grow by hundreds of blocks per day.
  64 The summary files are normally read before
  65 the accounting file, so that reports include
  66 all available information.
  67 .Pp
  68 If file names are supplied, they are read instead of
  69 .Pa /var/account/acct .
  70 After each file is read, if the summary
  71 files are being updated, an updated summary will
  72 be saved to disk.
  73 Only one report is printed,
  74 after the last file is processed.
  75 .Pp
  76 The labels used in the output indicate the following, except
  77 where otherwise specified by individual options:
  78 .Bl -tag -width k*sec
  79 .It Dv avio
  80 Average number of I/O operations per execution
  81 .It Dv cp
  82 Sum of user and system time, in minutes
  83 .It Dv cpu
  84 Same as
  85 .Dv cp
  86 .It Dv k
  87 CPU-time averaged core usage, in 1k units
  88 .It Dv k*sec
  89 CPU storage integral, in 1k-core seconds
  90 .It Dv re
  91 Real time, in minutes
  92 .It Dv s
  93 System time, in minutes
  94 .It Dv tio
  95 Total number of I/O operations
  96 .It Dv u
  97 User time, in minutes
  98 .El
  99 .Pp
 100 The options to
 101 .Nm
 102 are:
 103 .Bl -tag -width Ds
 104 .It Fl a
 105 List all command names, including those containing unprintable
 106 characters and those used only once.
 107 By default,
 108 .Nm
 109 places all names containing unprintable characters and
 110 those used only once under the name ``***other''.
 111 .It Fl b
 112 If printing command statistics, sort output by the sum of user and system
 113 time divided by number of calls.
 114 .It Fl c
 115 In addition to the number of calls and the user, system and real times
 116 for each command, print their percentage of the total over all commands.
 117 .It Fl d
 118 If printing command statistics, sort by the average number of disk
 119 I/O operations.
 120 If printing user statistics, print the average number of
 121 disk I/O operations per user.
 122 .It Fl D
 123 If printing command statistics, sort and print by the total number
 124 of disk I/O operations.
 125 .It Fl f
 126 Force no interactive threshold comparison with the
 127 .Fl v
 128 option.
 129 .It Fl i
 130 Do not read in the summary files.
 131 .It Fl j
 132 Instead of the total minutes per category, give seconds per call.
 133 .It Fl k
 134 If printing command statistics, sort by the cpu-time average memory
 135 usage.
 136 If printing user statistics, print the cpu-time average
 137 memory usage.
 138 .It Fl K
 139 If printing command statistics, print and sort by the cpu-storage integral.
 140 .It Fl l
 141 Separate system and user time; normally they are combined.
 142 .It Fl m
 143 Print per-user statistics rather than per-command statistics.
 144 .It Fl n
 145 Sort by number of calls.
 146 .It Fl q
 147 Create no output other than error messages.
 148 .It Fl r
 149 Reverse order of sort.
 150 .It Fl s
 151 Truncate the accounting files when done and merge their data
 152 into the summary files.
 153 .It Fl t
 154 For each command, report the ratio of real time to the sum
 155 of user and system cpu times.
 156 If the cpu time is too small to report, ``*ignore*'' appears in
 157 this field.
 158 .It Fl u
 159 Superseding all other flags, for each entry
 160 in the accounting file, print the user ID, total seconds of cpu usage,
 161 total memory usage, number of I/O operations performed, and
 162 command name.
 163 .It Fl v Ar cutoff
 164 For each command used
 165 .Ar cutoff
 166 times or fewer, print the command name and await a reply
 167 from the terminal.
 168 If the reply begins with ``y'', add
 169 the command to the category ``**junk**''.
 170 This flag is
 171 used to strip garbage from the report.
 172 .El
 173 .Pp
 174 By default, per-command statistics will be printed.
 175 The number of
 176 calls, the total elapsed time in minutes, total cpu and user time
 177 in minutes, average number of I/O operations, and CPU-time
 178 averaged core usage will be printed.
 179 If the
 180 .Fl m
 181 option is specified, per-user statistics will be printed, including
 182 the user name, the number of commands invoked, total cpu time used
 183 (in minutes), total number of I/O operations, and CPU storage integral
 184 for each user.
 185 If the
 186 .Fl u
 187 option is specified, the uid, user and system time (in seconds),
 188 CPU storage integral, I/O usage, and command name will be printed
 189 for each entry in the accounting data file.
 190 .Pp
 191 If the
 192 .Fl u
 193 flag is specified, all flags other than
 194 .Fl q
 195 are ignored.
 196 If the
 197 .Fl m
 198 flag is specified, only the
 199 .Fl b ,
 200 .Fl d ,
 201 .Fl i ,
 202 .Fl k ,
 203 .Fl q ,
 204 and
 205 .Fl s
 206 flags are honored.
 207 .Sh FILES
 208 .Bl -tag -width /var/account/usracct -compact
 209 .It Pa /var/account/acct
 210 raw accounting data file
 211 .It Pa /var/account/savacct
 212 per-command accounting summary database
 213 .It Pa /var/account/usracct
 214 per-user accounting summary database
 215 .El
 216 .Sh EXIT STATUS
 217 .Ex -std
 218 .Sh SEE ALSO
 219 .Xr lastcomm 1 ,
 220 .Xr acct 5 ,
 221 .Xr ac 8 ,
 222 .Xr accton 8
 223 .Sh CAVEATS
 224 While the behavior of the options in this version of
 225 .Nm
 226 was modeled after the original version, there are some intentional
 227 differences and undoubtedly some unintentional ones as well.
 228 In
 229 particular, the
 230 .Fl q
 231 option has been added, and the
 232 .Fl m
 233 option now understands more options than it used to.
 234 .Pp
 235 The formats of the summary files created by this version of
 236 .Nm
 237 are very different from the those used by the original version.
 238 This is not considered a problem, however, because the accounting record
 239 format has changed as well (since user ids are now 32 bits).
 240 .Sh AUTHORS
 241 .An Chris G. Demetriou Aq cgd@postgres.berkeley.edu
 242 .Sh BUGS
 243 The number of options to this program is absurd, especially considering
 244 that there is not much logic behind their lettering.
 245 .Pp
 246 The field labels should be more consistent.
 247 .Pp
 248 The VM system does not record the CPU storage integral.