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