Commit | Line | Data |
---|---|---|
65226554 PP |
1 | lttng-track(1) |
2 | ============== | |
e9711845 | 3 | :revdate: 14 June 2021 |
65226554 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
26f0c779 | 8 | lttng-track - Allow specific processes to record LTTng events |
65226554 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
26f0c779 | 13 | Allow specific processes to record Linux kernel events: |
de332339 JG |
14 | |
15 | [verse] | |
26f0c779 | 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] |
de332339 | 17 | (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... | |
26f0c779 PP |
18 | option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... | |
19 | option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)... | |
de332339 | 20 | |
de332339 | 21 | |
65226554 | 22 | [verse] |
26f0c779 PP |
23 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] |
24 | option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)... | |
de332339 | 25 | |
26f0c779 | 26 | Allow specific processes to record user space events: |
de332339 JG |
27 | |
28 | [verse] | |
26f0c779 PP |
29 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
30 | (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... | | |
31 | option:--vgid=VGROUP[,VGROUP]...)... | |
de332339 JG |
32 | |
33 | [verse] | |
26f0c779 | 34 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
de332339 | 35 | option:--all (option:--vpid | option:--vgid | option:--vuid)... |
65226554 PP |
36 | |
37 | ||
38 | DESCRIPTION | |
39 | ----------- | |
26f0c779 PP |
40 | The `lttng track` command allows one or more processes to record LTTng |
41 | events based on their attributes within: | |
65226554 | 42 | |
26f0c779 | 43 | With the option:--session='SESSION' option:: |
e9711845 | 44 | The recording session named 'SESSION'. |
65226554 | 45 | |
26f0c779 | 46 | Without the option:--session option:: |
e9711845 PP |
47 | The current recording session (see man:lttng-concepts(7) to learn |
48 | more about the current recording session). | |
65226554 | 49 | |
e9711845 | 50 | See man:lttng-concepts(7) to learn more about recording sessions and |
26f0c779 | 51 | recording event rules. |
9bd01b5e | 52 | |
26f0c779 | 53 | The `track` command adds values to _inclusion sets_ of process |
e9711845 | 54 | attributes. The available inclusion sets are, for a given recording |
26f0c779 | 55 | session: |
65226554 | 56 | |
26f0c779 PP |
57 | With the option:--kernel option:: |
58 | + | |
59 | * Process ID (PID). | |
de332339 | 60 | |
26f0c779 PP |
61 | * Virtual process ID (VPID). |
62 | + | |
63 | This is the PID as seen by the application. | |
65226554 | 64 | |
26f0c779 | 65 | * Unix user ID (UID). |
65226554 | 66 | |
26f0c779 PP |
67 | * Virtual Unix user ID (VUID). |
68 | + | |
69 | This is the UID as seen by the application. | |
70 | ||
71 | * Unix group ID (GID). | |
72 | ||
73 | * Virtual Unix group ID (VGID). | |
74 | + | |
75 | This is the GID as seen by the application. | |
76 | ||
77 | With the option:--userspace option:: | |
78 | + | |
79 | * VPID | |
80 | * VUID | |
81 | * VGID | |
82 | ||
83 | When an event{nbsp}__E__ satisfies all the other explicit and implicit | |
84 | conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if | |
85 | the attributes of the process for which LTTng creates{nbsp}__E__ are | |
e9711845 | 86 | *all* part of the inclusion sets of the recording session and domain |
26f0c779 PP |
87 | of{nbsp}__ER__. |
88 | ||
e9711845 | 89 | By default, on recording session creation (see man:lttng-create(1)), |
26f0c779 | 90 | all processes are allowed to record events. In other words, all the |
e9711845 | 91 | inclusion sets of the recording session contain all the possible |
26f0c779 PP |
92 | process attribute values. |
93 | ||
94 | If a given inclusion set{nbsp}__IS__ contains all the possible values | |
95 | (option:--all option), then using the `track` command to add one or more | |
96 | values{nbsp}__V__ to{nbsp}__IS__: | |
97 | ||
98 | . Removes all the values from{nbsp}__IS__. | |
99 | + | |
100 | This effectively makes{nbsp}__IS__ empty. | |
101 | ||
102 | . Adds{nbsp}__V__ to{nbsp}__IS__. | |
103 | ||
104 | Example: with the PID inclusion set, you can record all the system calls | |
105 | of a given process: | |
de332339 JG |
106 | |
107 | [role="term"] | |
108 | ---- | |
109 | $ lttng enable-event --kernel --all --syscall | |
110 | $ lttng track --kernel --pid=2345 | |
111 | $ lttng start | |
112 | ---- | |
113 | ||
da39b67c | 114 | See the ``<<examples,EXAMPLES>>'' section below for usage examples. |
4781283c | 115 | |
26f0c779 PP |
116 | Remove values from an inclusion set with the man:lttng-untrack(1) |
117 | command. | |
65226554 PP |
118 | |
119 | ||
26f0c779 PP |
120 | Inclusion set example |
121 | ~~~~~~~~~~~~~~~~~~~~~ | |
122 | This example operates on the Linux kernel process ID (PID) inclusion set | |
e9711845 | 123 | of the current recording session to show how an inclusion set works. |
65226554 | 124 | |
26f0c779 | 125 | Assume the maximum system PID is 7 for this example. |
65226554 | 126 | |
26f0c779 PP |
127 | . Initial inclusion set: |
128 | + | |
65226554 PP |
129 | ------------------------------- |
130 | [0] [1] [2] [3] [4] [5] [6] [7] | |
131 | ------------------------------- | |
132 | ||
26f0c779 PP |
133 | . Command: |
134 | + | |
d4f093aa | 135 | [role="term"] |
03c5529d | 136 | ---- |
de332339 | 137 | $ lttng track --kernel --pid=3,6,7 |
03c5529d | 138 | ---- |
26f0c779 PP |
139 | + |
140 | Inclusion set is now: | |
141 | + | |
65226554 PP |
142 | ------------------------------- |
143 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
144 | ------------------------------- | |
145 | ||
26f0c779 PP |
146 | . Command: |
147 | + | |
d4f093aa | 148 | [role="term"] |
03c5529d | 149 | ---- |
de332339 | 150 | $ lttng untrack --kernel --pid=7 |
03c5529d | 151 | ---- |
26f0c779 PP |
152 | + |
153 | Inclusion set is now: | |
154 | + | |
65226554 PP |
155 | ------------------------------- |
156 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
157 | ------------------------------- | |
158 | ||
26f0c779 PP |
159 | . Command: |
160 | + | |
d4f093aa | 161 | [role="term"] |
03c5529d | 162 | ---- |
de332339 | 163 | $ lttng track --kernel --pid=1,5 |
03c5529d | 164 | ---- |
26f0c779 PP |
165 | + |
166 | Inclusion set is now: | |
167 | + | |
65226554 PP |
168 | ------------------------------- |
169 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
170 | ------------------------------- | |
171 | ||
26f0c779 PP |
172 | Remove values from an inclusion set with the man:lttng-untrack(1) |
173 | command. | |
65226554 PP |
174 | |
175 | ||
f5511eea | 176 | include::common-lttng-cmd-options-head.txt[] |
65226554 PP |
177 | |
178 | ||
26f0c779 PP |
179 | Tracing domain |
180 | ~~~~~~~~~~~~~~ | |
65226554 PP |
181 | One of: |
182 | ||
183 | option:-k, option:--kernel:: | |
26f0c779 | 184 | Add values to one or more Linux kernel inclusion sets. |
65226554 PP |
185 | |
186 | option:-u, option:--userspace:: | |
26f0c779 | 187 | Add values to one or more user space inclusion sets. |
65226554 | 188 | |
26f0c779 PP |
189 | Recording target |
190 | ~~~~~~~~~~~~~~~~ | |
59b19c3c | 191 | option:-s 'SESSION', option:--session='SESSION':: |
e9711845 PP |
192 | Add values to one or more inclusion sets of the recording session |
193 | named 'SESSION' instead of the current recording session. | |
65226554 PP |
194 | |
195 | ||
26f0c779 PP |
196 | Inclusion set selection |
197 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
59b19c3c | 198 | option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: |
26f0c779 | 199 | For each 'PID' argument, add 'PID' to the process ID inclusion set |
e9711845 | 200 | of the selected recording session and domain. |
de332339 | 201 | + |
26f0c779 PP |
202 | 'PID' is the process ID attribute of a process as seen from the root |
203 | PID namespace (see man:pid_namespaces(7)). | |
65226554 | 204 | + |
26f0c779 | 205 | Only available with option:--kernel option. |
65226554 | 206 | |
de332339 | 207 | option:--vpid[='VPID'[,'VPID']...]:: |
26f0c779 | 208 | For each 'VPID' argument, add 'VPID' to the virtual process ID |
e9711845 | 209 | inclusion set of the selected recording session and domain. |
de332339 JG |
210 | + |
211 | 'VPID' is the virtual process ID attribute of a process as seen from | |
26f0c779 | 212 | the PID namespace of the process (see man:pid_namespaces(7)). |
9bd01b5e | 213 | |
de332339 | 214 | option:--uid[='USER'[,'USER']...]:: |
26f0c779 | 215 | For each 'USER' argument, add 'USER' to the user ID inclusion set of |
e9711845 | 216 | the selected recording session and domain. |
de332339 | 217 | + |
26f0c779 | 218 | 'USER' is either: |
de332339 | 219 | + |
26f0c779 PP |
220 | -- |
221 | * The real user ID (see man:getuid(3)) of a process as seen | |
222 | from the root user namespace (see man:user_namespaces(7)). | |
223 | ||
224 | * A user name. | |
225 | + | |
226 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs | |
227 | the user name resolution on addition to the user ID inclusion set. | |
228 | -- | |
9bd01b5e | 229 | + |
26f0c779 | 230 | Only available with option:--kernel option. |
9bd01b5e | 231 | |
26f0c779 PP |
232 | option:--vuid[='VUSER'[,'VUSER']...]:: |
233 | For each 'VUSER' argument, add 'VUSER' to the virtual user ID | |
e9711845 | 234 | inclusion set of the selected recording session and domain. |
9bd01b5e | 235 | + |
26f0c779 | 236 | 'VUSER' is either: |
de332339 | 237 | + |
26f0c779 PP |
238 | -- |
239 | * The real user ID (see man:getuid(3)) of a process as seen | |
240 | from the user namespace (see man:user_namespaces(7)). | |
241 | ||
242 | * A user name. | |
de332339 | 243 | + |
26f0c779 PP |
244 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
245 | the user name resolution on addition to the virtual user ID inclusion | |
246 | set. | |
247 | -- | |
9bd01b5e | 248 | |
de332339 | 249 | option:--gid[='GROUP'[,'GROUP']...]:: |
26f0c779 | 250 | For each 'GROUP' argument, add 'GROUP' to the group ID |
e9711845 | 251 | inclusion set of the selected recording session and domain. |
de332339 | 252 | + |
26f0c779 | 253 | 'GROUP' is either: |
9bd01b5e | 254 | + |
26f0c779 PP |
255 | -- |
256 | * The real group ID (see man:getgid(3)) of a process as seen from the | |
257 | root user namespace (see man:user_namespaces(7)). | |
258 | ||
259 | * A group name. | |
260 | + | |
261 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs | |
262 | the group name resolution on addition to the group ID inclusion set. | |
263 | -- | |
de332339 | 264 | + |
26f0c779 | 265 | Only available with option:--kernel option. |
9bd01b5e | 266 | |
26f0c779 PP |
267 | option:--vgid[='VGROUP'[,'VGROUP']...]:: |
268 | For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID | |
e9711845 | 269 | inclusion set of the selected recording session and domain. |
de332339 | 270 | + |
26f0c779 | 271 | 'VGROUP' is either: |
de332339 | 272 | + |
26f0c779 PP |
273 | -- |
274 | * The real group ID (see man:getgid(3)) of a process as seen | |
275 | from the user namespace (see man:user_namespaces(7)). | |
276 | ||
277 | * A group name. | |
9bd01b5e | 278 | + |
26f0c779 PP |
279 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
280 | the group name resolution on addition to the virtual group ID inclusion | |
281 | set. | |
282 | -- | |
283 | ||
284 | ||
285 | Inclusion set operation | |
286 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
287 | option:-a, option:--all:: | |
288 | With one or more empty option:--pid, option:--vpid, option:--uid, | |
289 | option:--vuid, option:--gid, and option:--vgid options: add *all* | |
290 | the possible values to the selected inclusion sets. | |
9bd01b5e | 291 | |
65226554 | 292 | |
f5511eea | 293 | include::common-lttng-cmd-help-options.txt[] |
65226554 PP |
294 | |
295 | ||
f5511eea PP |
296 | include::common-lttng-cmd-after-options.txt[] |
297 | ||
298 | ||
4781283c PP |
299 | [[examples]] |
300 | EXAMPLES | |
301 | -------- | |
e9711845 | 302 | .Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session. |
4781283c PP |
303 | ==== |
304 | See the option:--pid option. | |
305 | ||
306 | [role="term"] | |
307 | ---- | |
308 | $ lttng track --kernel --pid=1728,3775 | |
309 | ---- | |
310 | ==== | |
311 | ||
e9711845 | 312 | .Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session. |
4781283c PP |
313 | ==== |
314 | See the option:--vuid and option:--session options. | |
315 | ||
316 | [role="term"] | |
317 | ---- | |
318 | $ lttng track --userspace --session=my-session --vuid=http | |
319 | ---- | |
320 | ==== | |
321 | ||
e9711845 | 322 | .Add all the possible group IDs to the Linux kernel group ID inclusion set of the current recording session. |
4781283c PP |
323 | ==== |
324 | See the option:--all and option:--gid options. | |
325 | ||
326 | [role="term"] | |
327 | ---- | |
328 | $ lttng track --kernel --all --gid | |
329 | ---- | |
330 | ==== | |
331 | ||
332 | ||
f5511eea | 333 | include::common-footer.txt[] |
65226554 PP |
334 | |
335 | ||
336 | SEE ALSO | |
337 | -------- | |
26f0c779 | 338 | man:lttng(1), |
af1c4164 PP |
339 | man:lttng-untrack(1), |
340 | man:lttng-concepts(7) |