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.  If
 223 .Ar rawfile
 224 is
 225 .Li - ,
 226 the file will be written to
 227 .Xr stdout 4 .
 228 .\"
 229 .\"     ## trace -L ##
 230 .It Fl L Ar rawfile Fl S Ar seconds
 231 .Pp
 232 Copy the current trace buffer to
 233 .Ar rawfile
 234 and send all future trace events to
 235 .Ar rawfile .
 236 .Bl -tag -width Ds
 237 .It Fl S Ar seconds
 238 After
 239 .Ar seconds
 240 have elapsed, stop recording and exit.  If
 241 .Ar rawfile
 242 is
 243 .Li - ,
 244 the file will be written to
 245 .Xr stdout 4 .
 246 .El
 247 .\"
 248 .\"     ## trace -R ##
 249 .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 ...
 250 .Pp
 251 Read events from
 252 .Ar rawfile
 253 and print them in a human-readable format.
 254 .Bl -tag -width " "
 255 .It Fl F Ar frequency
 256 If
 257 .Ar rawfile
 258 does not contain clock frequency information, it can be specified with
 259 .Fl F .
 260 .It Fl X
 261 Force the binary format to be interpreted as 32-bit, as opposed to
 262 matching the width of the system running
 263 .Nm .
 264 .El
 265 .Pp
 266 See
 267 .Fl t
 268 for additional options.
 269 .El
 270 .Sh TRACE CODES FORMAT
 271 Event classes, subclasses, and codes are matched to names using a trace
 272 codes file.  Any events that cannot be matched will be referred to by
 273 their debugid in hex.
 274 .Pp
 275 The system-wide trace codes file is located at
 276 .Pa /usr/share/misc/trace.codes .
 277 Additional files are typically stored in
 278 .Pa /usr/local/share/misc .
 279 .Pp
 280 A code file consists of a list of tracepoints, one per line, with the
 281 tracepoint's debugid (component, subclass, and code) in hex, followed by
 282 a tab, followed by the tracepoint's name.
 283 .Pp
 284 For instance, the MSC_mach_msg_trap tracepoint is defined by
 285 .Pp
 286 .Dl 0x010c007c MSC_mach_msg_trap
 287 .Pp
 288 This describes the tracepoint with the following info:
 289 .Pp
 290 .Bl -column -offset indent "Subclass" "MSC_mach_msg_trap"
 291 .\" is this right?  We should refer to the shifting and kdebug.h
 292 .It Sy Name Ta MSC_mach_msg_trap
 293 .It Sy Class Ta 0x01 Ta (Mach events)
 294 .It Sy Subclass Ta 0x0c Ta (Mach system calls)
 295 .It Sy Code Ta 0x007c Ta (msg_trap)
 296 .El
 297 .Pp
 298 See
 299 .\" this absolute path no longer exists thanks to SDKs. :P
 300 .Pa /usr/include/sys/kdebug.h
 301 for class and subclass values.
 302 .Sh TRACEFILTER FORMAT
 303 A tracefilter description file consists of a list of class and subclass
 304 filters in hex, one per line, which are applied as if they were passed
 305 with
 306 .Fl c
 307 and
 308 .Fl s .
 309 Pass
 310 .Fl v
 311 to see what classes and subclasses are being set.
 312 .Pp
 313 Comment lines start with
 314 .Ql # ,
 315 class filter lines start with
 316 .Ql C ,
 317 and subclass filter lines start with
 318 .Ql S
 319 and include the class they apply to.
 320 .Pp
 321 For example, to trace Mach events (class 1):
 322 .Pp
 323 .Dl C 0x01
 324 .Pp
 325 And to trace Mach system calls (class 1, subclass 13):
 326 .Pp
 327 .Dl S 0x010C
 328 .Pp
 329 .Sh EXAMPLES
 330 .Nm
 331 usually requires multiple invocations in order to set up the trace
 332 buffers, enable the correct events, and collect the events.  A typical
 333 session with trace is:
 334 .Pp
 335 .Dl trace -i
 336 .Dl trace -e -c 1 -s 31
 337 .Dl sleep 1
 338 .Dl trace -d
 339 .Dl trace -t
 340 .Pp
 341 This initializes the trace buffers to their default values, enables the
 342 mach_msg_trap subclass of the MACH_SysCall class, waits for one second,
 343 then disables tracing and prints it to
 344 .Xr stdout 4 .
 345 This is useful for investigating isolated issues or gaining some
 346 understanding about a kernel subsystem.  If a specific execuable should
 347 be traced, with the events saved for later analysis, the sequence of
 348 commands would be:
 349 .Pp
 350 .Dl trace -i
 351 .Dl trace -E -c 0x4 ./my_prog
 352 .Dl trace -d
 353 .Dl trace -l tracefile
 354 .Dl trace -R tracefile
 355 .Pp
 356 This initializes the trace buffers, enables all events in the BSC_SysCall class and runs
 357 .Li my_prog ,
 358 disables tracing, collects events into
 359 .Li tracefile ,
 360 and finally prints those events out in a human-readable form.
 361 .Sh CAVEATS
 362 Almost all
 363 .Nm
 364 command flags require superuser (root) privileges.
 365 .Pp
 366 After failures, the trace buffers usually need to be re-initialized.
 367 .Pp
 368 .Sh DIAGNOSTICS
 369 .Ex -std
 370 .Sh SEE ALSO
 371 .Xr trace 4 ,
 372 .Xr fs_usage 1 ,
 373 .Xr sc_usage 1 ,
 374 .Xr latency 1 ,
 375 .Xr top 1