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 .Nd system activity reporter
  27 .Sh SYNOPSIS             \" Section Header - required - don't modify
  28 .Nm sar
  29 .Op Fl dgpu              \" [-dgpu]
  30 .Op Fl n Ar mode         \" [-n mode]
  31 .Op Fl o Ar filename     \" [-o filename]
  32 t                        \" t
  33 .Op Ar n                 \" [ n ]
  34 .Nm sar
  35 .Op Fl dgpu              \" [-dgpu]
  36 .Op Fl n Ar mode         \" [-n mode]
  37 .Op Fl e Ar time         \" [-e time]
  38 .Op Fl f Ar filename     \" [-f filename]
  39 .Op Fl i Ar seconds      \" [-i seconds]
  40 .Op Fl s Ar time         \" [-s time]
  41 .Sh DESCRIPTION          \" Section Header - required - don't modify
  42 The
  43 .Nm sar
  44 command is used to sample and report various cumulative statistic counters
  45 maintained by the operating system.
  46 It can be invoked in two different ways.
  47 .Pp
  48 In the first usage instance,
  49 .Ar n
  50 samples are reported at
  51 .Ar t
  52 second intervals.
  53 If
  54 .Ar n
  55 is not specified, only one sample will be captured.
  56 When the -o option is specified,
  57 .Nm sar
  58 will write the binary sampling data to the output file specified by
  59 .Ar filename .
  60 .Pp
  61 In the second usage instance,
  62 there is no on-going sample interval to specify.
  63 This is because the sampling input comes
  64 from a previously recorded, binary activity file.
  65 The binary activity file can be specified using the
  66 .Fl f Ar filename
  67 option.
  68 When the
  69 .Fl f
  70 option isn't used,
  71 .Nm sar
  72 attempts to open a default binary activity file,
  73 /var/log/sa/sadd, where
  74 .Ar dd
  75 represents the current day of the month.
  76 .Pp
  77 The starting and ending time of the report can be restricted using the
  78 .Fl e
  79 and
  80 .Fl s
  81 options.  Here, the
  82 .Ar time
  83 field is specified in the form hh[:mm[:ss]].
  84 .Pp
  85 Finally, the
  86 .Fl i
  87 option can be used to select the sampling interval.
  88 Only records at least
  89 .Ar seconds
  90 apart will be reported.
  91 When the
  92 .Fl i
  93 option is not used,
  94 all of the previously recorded interval samples are reported.
  95 .Pp
  96 Due to the nature of on-going sample collection,
  97 the data is reported in a verbose mode
  98 when more than one sampling option is specified.
  99 Column headers are printed at the beginning of the report;
 100 averages are printed when the
 101 .Nm sar
 102 command terminates.
 103 .Sh OPTIONS
 104 The following options restrict the sample set that
 105 .Nm sar
 106 reports.
 107 .Pp                      \" Inserts a space
 108 .Bl -tag -width -indent  \" Differs from above in tag removed
 109 .It Fl d
 110 Report disk activity.
 111 .Pp
 112 .Bl -tag -width -indent  \" Begins a tagged list
 113 .It device
 114 The BSD name of the device.
 115 .It r+w/s
 116 The number of reads and writes per second.
 117 .It blks/s
 118 Number of blocks (in device's default blocksize) transferred to a device per second.
 119 .El
 120 .It Fl g
 121 Report page-out activity.
 122 .Pp
 123 .Bl -tag -width -indent  \" Begins a tagged list
 124 .It pgout/s
 125 The number of pages paged out per second.
 126 .El
 127 .It Fl p
 128 Report page-in and page fault activity
 129 .Pp
 130 .Bl -tag -width -indent  \" Begins a tagged list
 131 .It pgin/s
 132 The number of pages paged in per second.
 133 .It pflts/s
 134 The number of faults that caused a page to be copied in per second.
 135 .It vflts/s
 136 The number of times vm_fault routine has been called.
 137 .El
 138 .It Fl n Ar mode
 139 Report network activity with modes
 140 .Ar DEV ,
 141 .Ar EDEV ,
 142 or
 143 .Ar PPP .
 144 Multiple network modes can be specified.
 145 .Pp
 146 .Bl -tag -width -indent \" Begins a tagged list
 147 .It DEV
 148 The
 149 .Ar DEV
 150 mode reports network device statistics.  The following
 151 information is displayed for each interface.
 152 .Pp
 153 .Bl -tag -width "Obytes/s" \" Begins a tagged list
 154 .It IFACE
 155 The network interface name.
 156 .It Ipkts/s
 157 The number of packets received per second.
 158 .It Ibytes/s
 159 The number of bytes received per second.
 160 .It Opkts/s
 161 The number of packets sent per second.
 162 .It Obytes/s
 163 The number of bytes sent per second.
 164 .El
 165 .It EDEV
 166 The
 167 .Ar EDEV
 168 mode reports network device error statistics. The
 169 following information is displayed for each interface.
 170 .Pp
 171 .Bl -tag -width "Drops/s" \" Begins a tagged list
 172 .It IFACE
 173 The interface name.
 174 .It Ierrs/s
 175 The input errors per second.
 176 .It Oerrs/s
 177 The output errors per second.
 178 .It Coll/s
 179 The collisions that occurred per second.
 180 .It Drops/s
 181 The number of dropped packets per second.
 182 .El
 183 .It PPP
 184 The
 185 .Ar PPP
 186 mode must be specified in order to display ppp connections
 187 in the network statistics. This will also turn on the PPP modify
 188 mode in
 189 .Ar sadc
 190 (8) when sampling data is not being read from a file.
 191 By default, both the collection and reporting of ppp
 192 statistics is turned off.  See
 193 .Ar sadc
 194 (8).
 195 .El
 196 .Pp
 197 .It Fl u
 198 Report CPU activity (default)
 199 .Pp
 200 %usr, %sys, and %idle
 201 .Pp
 202 These report the percentage of time running in user mode,
 203 system mode and idle.
 204 .El
 205 .Sh FILES                \" File used or created by the topic of the man page
 206 .Bl -tag -width "/var/log/sa/sadd" -compact
 207 .It Pa /var/log/sa/sadd
 208 Default daily activity file that holds the binary sampling data.
 209 .Ar dd
 210 are digits that represent the day of the month.
 211 .El
 212 .Sh SEE ALSO
 213 .\" List links in ascending order by section, alphabetically within a section.
 214 .Xr fs_usage 1 ,
 215 .Xr netstat 1 ,
 216 .Xr sc_usage 1 ,
 217 .Xr top 1 ,
 218 .Xr vm_stat 1 ,
 219 .Xr iostat 8 ,
 220 .Xr sa1 8 ,
 221 .Xr sa2 8 ,
 222 .Xr sadc 8
 223 .\" .Sh BUGS              \" Document known, unremedied bugs