docs/performance/dtrace.md

   1 # dtrace
   2
   3 `dtrace` is a powerful Mac OS X kernel instrumentation system that can
   4 be used to profile wakeups. This article provides a light introduction
   5 to it.
   6
   7 :::
   8 **Note**: The [power profiling overview](power_profiling_overview.md) is
   9 worth reading at this point if you haven't already. It may make parts
  10 of this document easier to understand.
  11 :::
  12
  13 ## Invocation
  14
  15 `dtrace` must be invoked as the super-user. A good starting command for
  16 profiling wakeups is the following.
  17
  18 ```
  19 sudo dtrace -n 'mach_kernel::wakeup { @[ustack()] = count(); }' -p $FIREFOX_PID > $OUTPUT_FILE
  20 ```
  21
  22 Let's break that down further.
  23
  24 -   The` -n` option combined with the `mach_kernel::wakeup` selects a
  25     *probe point*. `mach_kernel` is the *module name* and `wakeup` is
  26     the *probe name*. You can see a complete list of probes by running
  27     `sudo dtrace -l`.
  28 -   The code between the braces is run when the probe point is hit. The
  29     above code counts unique stack traces when wakeups occur; `ustack`
  30     is short for \"user stack\", i.e. the stack of the userspace program
  31     executing.
  32
  33 Run that command for a few seconds and then hit [Ctrl]{.kbd} + [C]{.kbd}
  34 to interrupt it. `dtrace` will then print to the output file a number of
  35 stack traces, along with a wakeup count for each one. The ordering of
  36 the stack traces can be non-obvious, so look at them carefully.
  37
  38 Sometimes the stack trace has less information than one would like.
  39 It's unclear how to improve upon this.
  40
  41 ## See also
  42
  43 dtrace is *very* powerful, and you can learn more about it by consulting
  44 the following resources:
  45
  46 -   [The DTrace one-liner
  47     tutorial](https://wiki.freebsd.org/DTrace/Tutorial) from FreeBSD.
  48 -   [DTrace tools](http://www.brendangregg.com/dtrace.html), by Brendan
  49     Gregg.