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