Commit | Line | Data |
---|---|---|
e008a9af PP |
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"> | |
3ec32306 | 98 | lttng untrack --pid --all |
e008a9af PP |
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> |