fd854c03c030bd0940eeefe3b0f1e1928fbe70c3
[lttng-tools.git] / doc / man / lttng-track.1.txt
1 lttng-track(1)
2 ==============
3 :revdate: 14 June 2021
4
5
6 NAME
7 ----
8 lttng-track - Allow specific processes to record LTTng events
9
10
11 SYNOPSIS
12 --------
13 Allow specific processes to record Linux kernel events:
14
15 [verse]
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION']
17 (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
18 option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... |
19 option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)...
20
21
22 [verse]
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)...
25
26 Allow specific processes to record user space events:
27
28 [verse]
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]...)...
32
33 [verse]
34 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION']
35 option:--all (option:--vpid | option:--vgid | option:--vuid)...
36
37
38 DESCRIPTION
39 -----------
40 The `lttng track` command allows one or more processes to record LTTng
41 events based on their attributes within:
42
43 With the option:--session='SESSION' option::
44 The recording session named 'SESSION'.
45
46 Without the option:--session option::
47 The current recording session (see man:lttng-concepts(7) to learn
48 more about the current recording session).
49
50 See man:lttng-concepts(7) to learn more about recording sessions and
51 recording event rules.
52
53 The `track` command adds values to _inclusion sets_ of process
54 attributes. The available inclusion sets are, for a given recording
55 session:
56
57 With the option:--kernel option::
58 +
59 * Process ID (PID).
60
61 * Virtual process ID (VPID).
62 +
63 This is the PID as seen by the application.
64
65 * Unix user ID (UID).
66
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
86 *all* part of the inclusion sets of the recording session and domain
87 of{nbsp}__ER__.
88
89 By default, on recording session creation (see man:lttng-create(1)),
90 all processes are allowed to record events. In other words, all the
91 inclusion sets of the recording session contain all the possible
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:
106
107 [role="term"]
108 ----
109 $ lttng enable-event --kernel --all --syscall
110 $ lttng track --kernel --pid=2345
111 $ lttng start
112 ----
113
114 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
115
116 Remove values from an inclusion set with the man:lttng-untrack(1)
117 command.
118
119
120 Inclusion set example
121 ~~~~~~~~~~~~~~~~~~~~~
122 This example operates on the Linux kernel process ID (PID) inclusion set
123 of the current recording session to show how an inclusion set works.
124
125 Assume the maximum system PID is 7 for this example.
126
127 . Initial inclusion set:
128 +
129 -------------------------------
130 [0] [1] [2] [3] [4] [5] [6] [7]
131 -------------------------------
132
133 . Command:
134 +
135 [role="term"]
136 ----
137 $ lttng track --kernel --pid=3,6,7
138 ----
139 +
140 Inclusion set is now:
141 +
142 -------------------------------
143 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
144 -------------------------------
145
146 . Command:
147 +
148 [role="term"]
149 ----
150 $ lttng untrack --kernel --pid=7
151 ----
152 +
153 Inclusion set is now:
154 +
155 -------------------------------
156 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
157 -------------------------------
158
159 . Command:
160 +
161 [role="term"]
162 ----
163 $ lttng track --kernel --pid=1,5
164 ----
165 +
166 Inclusion set is now:
167 +
168 -------------------------------
169 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
170 -------------------------------
171
172 Remove values from an inclusion set with the man:lttng-untrack(1)
173 command.
174
175
176 include::common-lttng-cmd-options-head.txt[]
177
178
179 Tracing domain
180 ~~~~~~~~~~~~~~
181 One of:
182
183 option:-k, option:--kernel::
184 Add values to one or more Linux kernel inclusion sets.
185
186 option:-u, option:--userspace::
187 Add values to one or more user space inclusion sets.
188
189 Recording target
190 ~~~~~~~~~~~~~~~~
191 option:-s 'SESSION', option:--session='SESSION'::
192 Add values to one or more inclusion sets of the recording session
193 named 'SESSION' instead of the current recording session.
194
195
196 Inclusion set selection
197 ~~~~~~~~~~~~~~~~~~~~~~~
198 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
199 For each 'PID' argument, add 'PID' to the process ID inclusion set
200 of the selected recording session and domain.
201 +
202 'PID' is the process ID attribute of a process as seen from the root
203 PID namespace (see man:pid_namespaces(7)).
204 +
205 Only available with option:--kernel option.
206
207 option:--vpid[='VPID'[,'VPID']...]::
208 For each 'VPID' argument, add 'VPID' to the virtual process ID
209 inclusion set of the selected recording session and domain.
210 +
211 'VPID' is the virtual process ID attribute of a process as seen from
212 the PID namespace of the process (see man:pid_namespaces(7)).
213
214 option:--uid[='USER'[,'USER']...]::
215 For each 'USER' argument, add 'USER' to the user ID inclusion set of
216 the selected recording session and domain.
217 +
218 'USER' is either:
219 +
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 --
229 +
230 Only available with option:--kernel option.
231
232 option:--vuid[='VUSER'[,'VUSER']...]::
233 For each 'VUSER' argument, add 'VUSER' to the virtual user ID
234 inclusion set of the selected recording session and domain.
235 +
236 'VUSER' is either:
237 +
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.
243 +
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 --
248
249 option:--gid[='GROUP'[,'GROUP']...]::
250 For each 'GROUP' argument, add 'GROUP' to the group ID
251 inclusion set of the selected recording session and domain.
252 +
253 'GROUP' is either:
254 +
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 --
264 +
265 Only available with option:--kernel option.
266
267 option:--vgid[='VGROUP'[,'VGROUP']...]::
268 For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID
269 inclusion set of the selected recording session and domain.
270 +
271 'VGROUP' is either:
272 +
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.
278 +
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.
291
292
293 include::common-lttng-cmd-help-options.txt[]
294
295
296 include::common-lttng-cmd-after-options.txt[]
297
298
299 [[examples]]
300 EXAMPLES
301 --------
302 .Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session.
303 ====
304 See the option:--pid option.
305
306 [role="term"]
307 ----
308 $ lttng track --kernel --pid=1728,3775
309 ----
310 ====
311
312 .Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session.
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
322 .Add all the possible group IDs to the Linux kernel group ID inclusion set of the current recording session.
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
333 include::common-footer.txt[]
334
335
336 SEE ALSO
337 --------
338 man:lttng(1),
339 man:lttng-untrack(1),
340 man:lttng-concepts(7)
This page took 0.036625 seconds and 4 git commands to generate.