contents/using-lttng/controlling-tracing/pid-tracking.md

   1 ---
   2 id: pid-tracking
   3 since: 2.7
   4 ---
   5
   6 It's often useful to allow only specific process IDs (PIDs) to emit
   7 enabled events. For example, you may wish to record all the system
   8 calls made by a given process (à la
   9 <a href="http://linux.die.net/man/1/strace" class="ext">strace</a>).
  10
  11 The `lttng track` and `lttng untrack` commands serve this purpose. Both
  12 commands operate on a whitelist of process IDs. The `track` command
  13 adds entries to this whitelist while the `untrack` command removes
  14 entries. Any process having one of the PIDs in the whitelist is allowed
  15 to emit [enabled](#doc-enabling-disabling-events) LTTng events.
  16
  17 <div class="tip">
  18 <p>
  19     <span class="t">Note:</span>The PID tracker tracks the
  20     <em>numeric process IDs</em>. Should a process with a given tracked
  21     ID exit and another process be given this ID, then the latter would
  22     also be allowed to emit events.
  23 </p>
  24 </div>
  25
  26 For the sake of the following examples, assume the target system has 16
  27 possible PIDs. When a [tracing session](#doc-creating-destroying-tracing-sessions)
  28 is created, the whitelist contains all the possible PIDs:
  29
  30 <figure class="img img-100">
  31 <img src="/images/docs27/track-all.png" alt="All PIDs are tracked">
  32 <figcaption>All PIDs are tracked</figcaption>
  33 </figure>
  34
  35 When the whitelist is full and the `track` command is executed to specify
  36 some PIDs to track, the whitelist is first cleared, then the specific
  37 PIDs are tracked. For example, after
  38
  39 <pre class="term">
  40 lttng track --pid 3,4,7,10,13
  41 </pre>
  42
  43 the whitelist is:
  44
  45 <figure class="img img-100">
  46 <img src="/images/docs27/track-3-4-7-10-13.png" alt="PIDs 3, 4, 7, 10, and 13 are tracked">
  47 <figcaption>PIDs 3, 4, 7, 10, and 13 are tracked</figcaption>
  48 </figure>
  49
  50 More PIDs can be added to the whitelist afterwards:
  51
  52 <pre class="term">
  53 lttng track --pid 1,15,16
  54 </pre>
  55
  56 gives:
  57
  58 <figure class="img img-100">
  59 <img src="/images/docs27/track-1-3-4-7-10-13-15-16.png" alt="PIDs 1, 15, and 16 are added to the whitelist">
  60 <figcaption>PIDs 1, 15, and 16 are added to the whitelist</figcaption>
  61 </figure>
  62
  63 The `untrack` command removes entries from the PID tracker's whitelist.
  64 Given the last example, the following command:
  65
  66 <pre class="term">
  67 lttng untrack --pid 3,7,10,13
  68 </pre>
  69
  70 leads to this whitelist:
  71
  72 <figure class="img img-100">
  73 <img src="/images/docs27/track-1-4-15-16.png" alt="PIDs 3, 7, 10, and 13 are removed from the whitelist">
  74 <figcaption>PIDs 3, 7, 10, and 13 are removed from the whitelist</figcaption>
  75 </figure>
  76
  77 All possible PIDs can be tracked again using the `--all` option of
  78 `lttng track`:
  79
  80 <pre class="term">
  81 lttng track --pid --all
  82 </pre>
  83
  84 gives:
  85
  86 <figure class="img img-100">
  87 <img src="/images/docs27/track-all.png" alt="All PIDs are tracked">
  88 <figcaption>All PIDs are tracked</figcaption>
  89 </figure>
  90
  91 A very typical use case with PID tracking is starting with an empty
  92 whitelist, then [starting the tracers](#doc-basic-tracing-session-control),
  93 and then adding PIDs manually while tracing is active. This can be
  94 accomplished by using the `--all` option of the `untrack` command
  95 to clear the whitelist after a tracing session is created:
  96
  97 <pre class="term">
  98 lttng untrack --pid --all
  99 </pre>
 100
 101 gives:
 102
 103 <figure class="img img-100">
 104 <img src="/images/docs27/untrack-all.png" alt="No PIDs are tracked">
 105 <figcaption>No PIDs are tracked</figcaption>
 106 </figure>
 107
 108 Tracing with this whitelist configuration does not produce any event
 109 because no processes are tracked. The `track` command can be used
 110 as usual to track specific PIDs, for example:
 111
 112 <pre class="term">
 113 lttng track --pid 6,11
 114 </pre>
 115
 116 results in:
 117
 118 <figure class="img img-100">
 119 <img src="/images/docs27/track-6-11.png" alt="PIDs 6 and 11 are tracked">
 120 <figcaption>PIDs 6 and 11 are tracked</figcaption>
 121 </figure>