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