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