trace.tproj/trace.1

   1 .\" Copyright (c) 2010, Apple Inc.  All rights reserved.
   2 .\"
   3 .Dd April 3, 2015
   4 .Dt TRACE 1
   5 .Os "Mac OS X"
   6 .Sh NAME
   7 .Nm trace
   8 .Nd configure, record, and display kernel trace events
   9 .Sh SYNOPSIS
  10 .Bl -hang -compact -width "trace -"
  11 .\"
  12 .It Nm Fl d
  13 .Op Fl a Ar pid | Fl x Ar pid
  14 .\"
  15 .It Nm Fl e
  16 .Op Fl c Ar class Oo Fl p Ar end-class Oc Oo Fl s Ar subclass Oc
  17 .Op Fl a Ar pid | Fl x Ar pid
  18 .Op Fl k Ar code
  19 .Op Fl P
  20 .Op Fl T Ar filter-file
  21 .\"
  22 .It Nm Fl E
  23 .Op Fl c Ar class Oo Fl p Ar end-class Oc Oo Fl s Ar subclass Oc
  24 .Op Fl a Ar pid | Fl x Ar pid
  25 .Op Fl k Ar code
  26 .Op Fl P
  27 .Op Fl T Ar tracefilter
  28 .Ar command
  29 .Op Ar argument ...
  30 .\"
  31 .It Nm Fl h
  32 .\"
  33 .It Nm Fl i
  34 .Op Fl b Ar num-events
  35 .\"
  36 .It Nm Fl g
  37 .\"
  38 .It Nm Fl l Ar rawfile
  39 .\"
  40 .It Nm Fl L Ar rawfile
  41 .Op Fl S Ar secs
  42 .\"
  43 .It Nm Fl n
  44 .\"
  45 .It Nm Fl r
  46 .\"
  47 .It Nm Fl R Ar rawfile
  48 .Op Fl X
  49 .Op Fl F Ar frequency
  50 .Op Fl o Ar outfile
  51 .Op Fl N
  52 .Op Ar codesfile ...
  53 .\"
  54 .It Nm Fl t
  55 .Op Fl o Ar outfile
  56 .Op Fl N
  57 .Op Ar codesfile ...
  58 .El
  59 .Sh DESCRIPTION
  60 .Nm
  61 initializes and configures the kernel trace subsystem.  Trace events can
  62 be recorded to an in-memory buffer or logged directly to a file, and
  63 optionally converted to a human-readable, plain-text format.
  64 .Pp
  65 .Nm
  66 operates according to the command flag specified.
  67 .Sh COMMANDS
  68 .Bl -tag -width Ds
  69 .It Fl h
  70 Print a succinct help message to
  71 .Xr stdout 4 .
  72 .\"
  73 .\"     ## trace -i ##
  74 .It Fl i Op Fl b Ar num-events
  75 .Pp
  76 Initialize the kernel trace buffer.  This command is required before
  77 tracing.
  78 .Bl -tag -width Ds
  79 .It Fl b Ar num-events
  80 Set the number of events that can be stored in the kernel trace buffer.
  81 .Ar num-events
  82 is a decimal number of events.  The default (and minimum) value is 8192
  83 event records per logical CPU.  No more than half of available
  84 memory may be used by trace buffers, though running with a buffer this
  85 large is not recommended.
  86 .El
  87 .\"
  88 .\"     ## trace -g ##
  89 .It Fl g
  90 Print the current kernel trace buffer settings to
  91 .Xr stdout 4 .
  92 .\"
  93 .\"     ## trace -d ##
  94 .It Fl d Op Fl a Ar pid | Fl x Ar pid
  95 .Pp
  96 By default, disable collection of events.  This command does not remove
  97 the kernel trace buffer.
  98 .Bl -tag -width Ds
  99 .It Fl a Ar pid
 100 Disable event collection for the process identified by
 101 .Ar pid .
 102 .It Fl x Ar pid
 103 Stop excluding
 104 .Ar pid
 105 from the trace.
 106 This reenables event collection of events for.
 107 .Ar pid .
 108 .El
 109 .\"
 110 .\"     ## trace -r ##
 111 .It Fl r
 112 Remove the kernel trace buffer.
 113 .\"
 114 .\"     ## trace -n ##
 115 .It Fl n
 116 Disable ring buffer mode.  When set, the trace buffer will fill to capacity
 117 and then stop collecting events.  Ring buffer mode is sometimes called
 118 "head," "stop," or "no-wrap" mode.  By default, the trace buffer will
 119 wrap around, overwriting previous events.  The default behavior is
 120 sometimes called windowed or wrap-around mode.
 121 .\"
 122 .\"     ## trace -e ##
 123 .Bk -words
 124 .It Xo Fl e
 125 .Op Fl c Ar class Oo Fl p Ar end-class Oc Oo Fl s Ar subclass Oc
 126 .Op Fl a Ar pid | Fl x Ar pid
 127 .Op Fl k Ar code ...
 128 .Op Fl P
 129 .Op Fl T Ar filter-file
 130 .Ek
 131 .Xc
 132 .Pp
 133 Enable collection of events.  By default, all events are collected.
 134 .Pp
 135 Options can be used to restrict collection to specific classes, class
 136 ranges, subclasses, and codes.  Classes and subclasses can be specified
 137 any number of times, but only 4 codes can be filtered at once.  Values
 138 can be specified in hex (0x...), decimal, or octal (0...).
 139 .Bl -tag -width " "
 140 .It Fl c Ar class
 141 Restrict collection to the events with the specified
 142 .Ar class .
 143 This option can be specified any number of times to collect events from
 144 more classes.
 145 .Bl -tag -width " "
 146 .It Fl p Ar end-class
 147 Provide an ending class to restrict collection to events in an inclusive
 148 range of classes between
 149 .Ar class
 150 and
 151 .Ar end-class .
 152 .It Fl s Ar subclass
 153 Restrict collection to the events with the specified
 154 .Ar subclass .
 155 .El
 156 .It Fl a Ar pid
 157 Restrict collection to to those events emitted by the process identified
 158 by
 159 .Ar pid .
 160 .It Fl x Ar pid
 161 Exclude events emitted by the process identified by
 162 .Ar pid .
 163 .It Fl k Ar code
 164 Restrict collection to events with the specified
 165 .Ar code .
 166 This option can be specified up to 4 times, and applies to all classes
 167 being collected.
 168 .It Fl T Ar filter-file
 169 Restrict collection to events specified in the provided
 170 .Ar filter-file .
 171 See
 172 .Sx TRACEFILTER FORMAT
 173 for details.
 174 .It Xo Fl P
 175 Restrict collection to PPT events.  This special collection of trace
 176 events provides insight into system performance.
 177 .Xc
 178 .El
 179 .\"
 180 .\"     ## trace -E ##
 181 .Bk -words
 182 .It Xo Fl E
 183 .Op Fl c Ar class Oo Fl p Ar end-class Oc Oo Fl s Ar subclass Oc
 184 .Op Fl a Ar pid | Fl x Ar pid
 185 .Op Fl k Ar code ...
 186 .Op Fl P
 187 .Op Fl T Ar filter-file
 188 .Ar command Op args ...
 189 .Ek
 190 .Xc
 191 .Pp
 192 Execute
 193 .Ar command
 194 with trace collection enabled for events emitted by the process.  See
 195 .Fl e
 196 for more information.
 197 .\"
 198 .\"     ## trace -t ##
 199 .It Fl t Oo Fl o Ar outfile Oc Oo Fl N Oc Oo Ar codesfile ... Oc
 200 .Pp
 201 Extract events from the kernel trace buffer and print them in a formatted,
 202 plain-text representation.  Additional code files can be specified to
 203 help
 204 .Nm
 205 find the names of unknown events.  For more information on the formatting
 206 process, see
 207 .Sx TRACE CODES FORMAT .
 208 .Bl -tag -width Ds
 209 .It Fl o Ar outfile
 210 Output the plain-text events to
 211 .Ar outfile .
 212 .It Fl N
 213 Ignore the system-wide trace codes file when getting names of events.
 214 Additional trace codes files specified will still be used.
 215 .El
 216 .\"
 217 .\"     ## trace -l ##
 218 .It Fl l Ar rawfile
 219 .Pp
 220 Empty the current kernel trace buffer into
 221 .Ar rawfile
 222 in a binary format.
 223 .\"
 224 .\"     ## trace -L ##
 225 .It Fl L Ar rawfile Fl S Ar seconds
 226 .Pp
 227 Copy the current trace buffer to
 228 .Ar rawfile
 229 and send all future trace events to
 230 .Ar rawfile .
 231 .Bl -tag -width Ds
 232 .It Fl S Ar seconds
 233 After
 234 .Ar seconds
 235 have elapsed, stop recording and exit.
 236 .El
 237 .\"
 238 .\"     ## trace -R ##
 239 .It Fl R Ar rawfile Oo Fl o Ar outfile Oc Oo Fl N Oc Oo Fl F Ar frequency Oc Oo Fl X Oc Op Ar codesfile ...
 240 .Pp
 241 Read events from
 242 .Ar rawfile
 243 and print them in a human-readable format.
 244 .Bl -tag -width " "
 245 .It Fl F Ar frequency
 246 If
 247 .Ar rawfile
 248 does not contain clock frequency information, it can be specified with
 249 .Fl F .
 250 .It Fl X
 251 Force the binary format to be interpreted as 32-bit, as opposed to
 252 matching the width of the system running
 253 .Nm .
 254 .El
 255 .Pp
 256 See
 257 .Fl t
 258 for additional options.
 259 .El
 260 .Sh TRACE CODES FORMAT
 261 Event classes, subclasses, and codes are matched to names using a trace
 262 codes file.  Any events that cannot be matched will be referred to by
 263 their debugid in hex.
 264 .Pp
 265 The system-wide trace codes file is located at
 266 .Pa /usr/share/misc/trace.codes .
 267 Additional files are typically stored in
 268 .Pa /usr/local/share/misc .
 269 .Pp
 270 A code file consists of a list of tracepoints, one per line, with the
 271 tracepoint's debugid (component, subclass, and code) in hex, followed by
 272 a tab, followed by the tracepoint's name.
 273 .Pp
 274 For instance, the MSC_mach_msg_trap tracepoint is defined by
 275 .Pp
 276 .Dl 0x010c007c MSC_mach_msg_trap
 277 .Pp
 278 This describes the tracepoint with the following info:
 279 .Pp
 280 .Bl -column -offset indent "Subclass" "MSC_mach_msg_trap"
 281 .\" is this right?  We should refer to the shifting and kdebug.h
 282 .It Sy Name Ta MSC_mach_msg_trap
 283 .It Sy Class Ta 0x01 Ta (Mach events)
 284 .It Sy Subclass Ta 0x0c Ta (Mach system calls)
 285 .It Sy Code Ta 0x007c Ta (msg_trap)
 286 .El
 287 .Pp
 288 See
 289 .\" this absolute path no longer exists thanks to SDKs. :P
 290 .Pa /usr/include/sys/kdebug.h
 291 for class and subclass values.
 292 .Sh TRACEFILTER FORMAT
 293 A tracefilter description file consists of a list of class and subclass
 294 filters in hex, one per line, which are applied as if they were passed
 295 with
 296 .Fl c
 297 and
 298 .Fl s .
 299 Pass
 300 .Fl v
 301 to see what classes and subclasses are being set.
 302 .Pp
 303 Comment lines start with
 304 .Ql # ,
 305 class filter lines start with
 306 .Ql C ,
 307 and subclass filter lines start with
 308 .Ql S
 309 and include the class they apply to.
 310 .Pp
 311 For example, to trace Mach events (class 1):
 312 .Pp
 313 .Dl C 0x01
 314 .Pp
 315 And to trace Mach system calls (class 1, subclass 13):
 316 .Pp
 317 .Dl S 0x010C
 318 .Pp
 319 .Sh EXAMPLES
 320 .Nm
 321 usually requires multiple invocations in order to set up the trace
 322 buffers, enable the correct events, and collect the events.  A typical
 323 session with trace is:
 324 .Pp
 325 .Dl trace -i
 326 .Dl trace -e -c 1 -s 31
 327 .Dl sleep 1
 328 .Dl trace -d
 329 .Dl trace -t
 330 .Pp
 331 This initializes the trace buffers to their default values, enables the
 332 mach_msg_trap subclass of the MACH_SysCall class, waits for one second,
 333 then disables tracing and prints it to
 334 .Xr stdout 4 .
 335 This is useful for investigating isolated issues or gaining some
 336 understanding about a kernel subsystem.  If a specific execuable should
 337 be traced, with the events saved for later analysis, the sequence of
 338 commands would be:
 339 .Pp
 340 .Dl trace -i
 341 .Dl trace -E -c 0x4 ./my_prog
 342 .Dl trace -d
 343 .Dl trace -l tracefile
 344 .Dl trace -R tracefile
 345 .Pp
 346 This initializes the trace buffers, enables all events in the BSC_SysCall class and runs
 347 .Li my_prog ,
 348 disables tracing, collects events into
 349 .Li tracefile ,
 350 and finally prints those events out in a human-readable form.
 351 .Sh CAVEATS
 352 Almost all
 353 .Nm
 354 command flags require superuser (root) privileges.
 355 .Pp
 356 After failures, the trace buffers usually need to be re-initialized.
 357 .Pp
 358 .Sh DIAGNOSTICS
 359 .Ex -std
 360 .Sh SEE ALSO
 361 .Xr trace 4 ,
 362 .Xr fs_usage 1 ,
 363 .Xr sc_usage 1 ,
 364 .Xr latency 1 ,
 365 .Xr top 1