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 .Dd February 14, 2020
  31 .Dt SA 8
  32 .Os
  33 .Sh NAME
  34 .Nm sa
  35 .Nd print system accounting statistics
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl abcdDfijkKlmnqrstu
  39 .Op Fl P Ar file
  40 .Op Fl U Ar file
  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 P Ar file
 147 Use the specified
 148 .Ar file
 149 for accessing the per-command accounting summary database,
 150 instead of the default
 151 .Pa /var/account/savacct .
 152 .It Fl q
 153 Create no output other than error messages.
 154 .It Fl r
 155 Reverse order of sort.
 156 .It Fl s
 157 Truncate the accounting files when done and merge their data
 158 into the summary files.
 159 .It Fl t
 160 For each command, report the ratio of real time to the sum
 161 of user and system cpu times.
 162 If the cpu time is too small to report, ``*ignore*'' appears in
 163 this field.
 164 .It Fl U Ar file
 165 Use the specified
 166 .Ar file
 167 for accessing the per-user accounting summary database,
 168 instead of the default
 169 .Pa /var/account/usracct .
 170 .It Fl u
 171 Superseding all other flags, for each entry
 172 in the accounting file, print the user ID, total seconds of cpu usage,
 173 total memory usage, number of I/O operations performed, and
 174 command name.
 175 .It Fl v Ar cutoff
 176 For each command used
 177 .Ar cutoff
 178 times or fewer, print the command name and await a reply
 179 from the terminal.
 180 If the reply begins with ``y'', add
 181 the command to the category ``**junk**''.
 182 This flag is
 183 used to strip garbage from the report.
 184 .El
 185 .Pp
 186 By default, per-command statistics will be printed.
 187 The number of
 188 calls, the total elapsed time in minutes, total cpu and user time
 189 in minutes, average number of I/O operations, and CPU-time
 190 averaged core usage will be printed.
 191 If the
 192 .Fl m
 193 option is specified, per-user statistics will be printed, including
 194 the user name, the number of commands invoked, total cpu time used
 195 (in minutes), total number of I/O operations, and CPU storage integral
 196 for each user.
 197 If the
 198 .Fl u
 199 option is specified, the uid, user and system time (in seconds),
 200 CPU storage integral, I/O usage, and command name will be printed
 201 for each entry in the accounting data file.
 202 .Pp
 203 If the
 204 .Fl u
 205 flag is specified, all flags other than
 206 .Fl q
 207 are ignored.
 208 If the
 209 .Fl m
 210 flag is specified, only the
 211 .Fl b ,
 212 .Fl d ,
 213 .Fl i ,
 214 .Fl k ,
 215 .Fl q ,
 216 and
 217 .Fl s
 218 flags are honored.
 219 .Sh FILES
 220 .Bl -tag -width /var/account/usracct -compact
 221 .It Pa /var/account/acct
 222 raw accounting data file
 223 .It Pa /var/account/savacct
 224 per-command accounting summary database
 225 .It Pa /var/account/usracct
 226 per-user accounting summary database
 227 .El
 228 .Sh EXIT STATUS
 229 .Ex -std
 230 .Sh SEE ALSO
 231 .Xr lastcomm 1 ,
 232 .Xr acct 5 ,
 233 .Xr ac 8 ,
 234 .Xr accton 8
 235 .Sh HISTORY
 236 .Nm
 237 first appeared in
 238 .At v5 .
 239 .Nm
 240 was rewritten for
 241 .Nx 0.9a
 242 from the specification provided by various systems' manual pages.
 243 .Sh AUTHORS
 244 .An Chris G. Demetriou Aq Mt cgd@postgres.berkeley.edu
 245 .Sh CAVEATS
 246 While the behavior of the options in this version of
 247 .Nm
 248 was modeled after the original version, there are some intentional
 249 differences and undoubtedly some unintentional ones as well.
 250 In
 251 particular, the
 252 .Fl q
 253 option has been added, and the
 254 .Fl m
 255 option now understands more options than it used to.
 256 .Pp
 257 The formats of the summary files created by this version of
 258 .Nm
 259 are very different from the those used by the original version.
 260 This is not considered a problem, however, because the accounting record
 261 format has changed as well (since user ids are now 32 bits).
 262 .Sh BUGS
 263 The number of options to this program is absurd, especially considering
 264 that there is not much logic behind their lettering.
 265 .Pp
 266 The field labels should be more consistent.
 267 .Pp
 268 The VM system does not record the CPU storage integral.