sar.tproj/sar.1

   1 .\"Portions Copyright (c) 1999-2003 Apple Computer, Inc. All Rights
   2 .\"Reserved.
   3 .\"
   4 .\"This file contains Original Code and/or Modifications of Original Code
   5 .\"as defined in and that are subject to the Apple Public Source License
   6 .\"Version 2.0 (the 'License'). You may not use this file except in
   7 .\"compliance with the License. Please obtain a copy of the License at
   8 .\"http://www.opensource.apple.com/apsl/ and read it before using this
   9 .\"file.
  10 .\"
  11 .\"The Original Code and all software distributed under the License are
  12 .\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  13 .\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  14 .\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  15 .\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  16 .\"Please see the License for the specific language governing rights and
  17 .\"limitations under the License.
  18 .\"
  19 .\"     @(#)sadc.8
  20
  21 .Dd Jul 25, 2003               \" DATE
  22 .Dt sar 1      \" Program name and manual section number
  23 .Os "Mac OS X"
  24 .Sh NAME                 \" Section Header - required - don't modify
  25 .Nm sar
  26 .\" The following lines are read in generating the apropos(man -k) database. Use only key
  27 .\" words here as the database is built based on the words here and in the .ND line.
  28 .\" Use .Nm macro to designate other names for the documented program.
  29 .Nd system activity reporter
  30 .Sh SYNOPSIS             \" Section Header - required - don't modify
  31 .Nm
  32 .Op Fl dgpu              \" [-dgpu]
  33 .Op Fl n Ar mode         \" [-n mode]
  34 .Op Fl o Ar filename     \" [-o filename]
  35 t                        \" t
  36 .Op Ar n                 \" [ n ]
  37 .Nm
  38 .Op Fl dgpu              \" [-dgpu]
  39 .Op Fl n Ar mode         \" [-n mode]
  40 .Op Fl e Ar time         \" [-e time]
  41 .Op Fl f Ar filename     \" [-f filename]
  42 .Op Fl i Ar seconds      \" [-i seconds]
  43 .Op Fl s Ar time         \" [-s time]
  44 .Sh DESCRIPTION          \" Section Header - required - don't modify
  45 The
  46 .Nm
  47 command is used to sample and report various cumulative statistic counters
  48 maintained by the operating system.  It can be invoked in two different ways.
  49 .Pp
  50 In the first usage instance,
  51 .Ar n
  52 samples are reported at
  53 .Ar t
  54 second intervals.
  55 If
  56 .Ar n
  57 is not specified, only one sample will be captured.
  58 When the -o option is specified,
  59 .Nm
  60 will write the binary sampling data to the output file specified by
  61 .Ar filename .
  62 .Pp
  63 In the second usage instance, there is no on-going sample interval to specify.
  64 This is because the sampling input comes from a previously recorded, binary activity file.
  65 The binary activity file can be specified using the -f
  66 .Ar filename
  67 option.
  68 When the -f option isn't used,
  69 .Nm
  70 attempts to open a default binary activity file,
  71 /var/log/sa/sadd, where
  72 .Ar dd
  73 represents the current day of the month.
  74 The starting and ending time of the report can be restricted using the -e
  75 and -s options.  Here, the
  76 .Ar time
  77 field is specified in the form hh[:mm[:ss]].
  78 Finally, the -i option can be used to select the sampling interval.
  79 Only records at least
  80 .Ar seconds
  81 apart will be reported.
  82 When the -i option is not used, all of the previously recorded
  83 interval samples are reported.
  84 .Pp
  85 Due to the nature of on-going sample collection, the data is reported in a
  86 verbose mode when more than one sampling option is specified.
  87 Column headers are printed at the beginning of the report and averages are
  88 printed when the
  89 .Nm
  90 command terminates.
  91 .Sh OPTIONS
  92 The following options restrict the sample set that
  93 .Nm
  94 reports.
  95 .Pp                      \" Inserts a space
  96 .Bl -tag -width -indent  \" Differs from above in tag removed
  97 .It Fl d
  98 Report disk activity.
  99 .Pp
 100 .Bl -tag -width -indent  \" Begins a tagged list
 101 .It device
 102 The BSD name of the device.
 103 .It r+w/s
 104 The number of reads and writes per second.
 105 .It blks/s
 106 Number of blocks (in device's default blocksize) transferred to a device per second.
 107 .El
 108 .It Fl g
 109 Report page-out activity.
 110 .Pp
 111 .Bl -tag -width -indent  \" Begins a tagged list
 112 .It pgout/s
 113 The number of pages paged out per second.
 114 .El
 115 .It Fl p
 116 Report page-in and page fault activity
 117 .Pp
 118 .Bl -tag -width -indent  \" Begins a tagged list
 119 .It pgin/s
 120 The number of pages paged in per second.
 121 .It pflts/s
 122 The number of faults that caused a page to be copied in per second.
 123 .It vflts/s
 124 The number of times vm_fault routine has been called.
 125 .El
 126 .It Fl n Ar mode
 127 Report network activity with modes
 128 .Ar DEV ,
 129 .Ar EDEV ,
 130 or
 131 .Ar PPP .
 132 Multiple network modes can be specified.
 133 .Pp
 134 .Bl -tag -width -indent \" Begins a tagged list
 135 .It DEV
 136 The
 137 .Ar DEV
 138 mode reports network device statistics.  The following
 139 information is displayed for each interface.
 140 .Pp
 141 .Bl -tag -width "Obytes/s" \" Begins a tagged list
 142 .It IFACE
 143 The network interface name.
 144 .It Ipkts/s
 145 The number of packets received per second.
 146 .It Ibytes/s
 147 The number of bytes received per second.
 148 .It Opkts/s
 149 The number of packets sent per second.
 150 .It Obytes/s
 151 The number of bytes sent per second.
 152 .El
 153 .It EDEV
 154 The
 155 .Ar EDEV
 156 mode reports network device error statistics. The
 157 following information is displayed for each interface.
 158 .Pp
 159 .Bl -tag -width "Drops/s" \" Begins a tagged list
 160 .It IFACE
 161 The interface name.
 162 .It Ierrs/s
 163 The input errors per second.
 164 .It Oerrs/s
 165 The output errors per second.
 166 .It Coll/s
 167 The collisions that occurred per second.
 168 .It Drops/s
 169 The number of dropped packets per second.
 170 .El
 171 .It PPP
 172 The
 173 .Ar PPP
 174 mode must be specified in order to display ppp connections
 175 in the network statistics. This will also turn on the PPP modify
 176 mode in
 177 .Ar sadc
 178 (8) when sampling data is not being read from a file.
 179 By default, both the collection and reporting of ppp
 180 statistics is turned off.  See
 181 .Ar sadc
 182 (8).
 183 .El
 184 .Pp
 185 .It Fl u
 186 Report CPU activity (default)
 187 .Pp
 188 %usr, %sys, and %idle
 189 .Pp
 190 These report the percentage of time running in user mode,
 191 system mode and idle.
 192 .El
 193 .Sh FILES                \" File used or created by the topic of the man page
 194 .Bl -tag -width "/var/log/sa/sadd" -compact
 195 .It Pa /var/log/sa/sadd
 196 Default daily activity file that holds the binary sampling data.
 197 .Ar dd
 198 are digits that represent the day of the month.
 199 .El
 200 .Sh SEE ALSO
 201 .\" List links in ascending order by section, alphabetically within a section.
 202 .Xr sa1 8 ,
 203 .Xr sa2 8 ,
 204 .Xr sadc 8 ,
 205 .Xr iostat 8 ,
 206 .Xr vm_stat 1 ,
 207 .Xr netstat 1 ,
 208 .Xr top 1 ,
 209 .Xr sc_usage 1 ,
 210 .Xr fs_usage 1
 211 .\" .Sh BUGS              \" Document known, unremedied bugs