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>).
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.
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.
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:
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>
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
40 lttng track --pid 3,4,7,10,13
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>
50 More PIDs can be added to the whitelist afterwards:
53 lttng track --pid 1,15,16
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>
63 The `untrack` command removes entries from the PID tracker's whitelist.
64 Given the last example, the following command:
67 lttng untrack --pid 3,7,10,13
70 leads to this whitelist:
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>
77 All possible PIDs can be tracked again using the `--all` option of
81 lttng track --pid --all
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>
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:
98 lttng untrack --pid --all
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>
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:
113 lttng track --pid 6,11
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>