lttng-track(1)

1LTTNG-TRACK(1)                   LTTng Manual                   LTTNG-TRACK(1)
2
3
4

NAME

6       lttng-track - Allow specific processes to record LTTng events
7

SYNOPSIS

9       Allow specific processes to record Linux kernel events:
10
11       lttng [GENERAL OPTIONS] track --kernel [--session=SESSION]
12             (--pid=PID[,PID]... | --vpid=VPID[,VPID]... |
13              --uid=UID[,UID]... | --vuid=VUSER[,VUSER]... |
14              --gid=GID[,GID]... | --vgid=VGROUP[,VGROUP]...)...
15
16       lttng [GENERAL OPTIONS] track --kernel [--session=SESSION]
17             --all (--pid | --vpid | --uid | --vuid | --gid | --vgid)...
18
19       Allow specific processes to record user space events:
20
21       lttng [GENERAL OPTIONS] track --userspace [--session=SESSION]
22             (--vpid=VPID[,VPID]... | --vuid=VUSER[,VUSER]... |
23              --vgid=VGROUP[,VGROUP]...)...
24
25       lttng [GENERAL OPTIONS] track --userspace [--session=SESSION]
26             --all (--vpid | --vgid | --vuid)...
27

DESCRIPTION

29       The lttng track command allows one or more processes to record LTTng
30       events based on their attributes within:
31
32       With the --session=SESSION option
33           The recording session named SESSION.
34
35       Without the --session option
36           The current recording session (see lttng-concepts(7) to learn more
37           about the current recording session).
38
39       See lttng-concepts(7) to learn more about recording sessions and
40       recording event rules.
41
42       The track command adds values to inclusion sets of process attributes.
43       The available inclusion sets are, for a given recording session:
44
45       With the --kernel option
46
47           •   Process ID (PID).
48
49           •   Virtual process ID (VPID).
50
51               This is the PID as seen by the application.
52
53           •   Unix user ID (UID).
54
55           •   Virtual Unix user ID (VUID).
56
57               This is the UID as seen by the application.
58
59           •   Unix group ID (GID).
60
61           •   Virtual Unix group ID (VGID).
62
63               This is the GID as seen by the application.
64
65       With the --userspace option
66
67           •   VPID
68
69           •   VUID
70
71           •   VGID
72
73       When an event E satisfies all the other explicit and implicit
74       conditions of an event rule ER, ER matches E if the attributes of the
75       process for which LTTng creates E are all part of the inclusion sets of
76       the recording session and domain of ER.
77
78       By default, on recording session creation (see lttng-create(1)), all
79       processes are allowed to record events. In other words, all the
80       inclusion sets of the recording session contain all the possible
81       process attribute values.
82
83       If a given inclusion set IS contains all the possible values (--all
84       option), then using the track command to add one or more values V
85       to IS:
86
87        1. Removes all the values from IS.
88
89           This effectively makes IS empty.
90
91        2. Adds V to IS.
92
93       Example: with the PID inclusion set, you can record all the system
94       calls of a given process:
95
96           $ lttng enable-event --kernel --all --syscall
97           $ lttng track --kernel --pid=2345
98           $ lttng start
99
100       See the “EXAMPLES” section below for usage examples.
101
102       Remove values from an inclusion set with the lttng-untrack(1) command.
103
104   Inclusion set example
105       This example operates on the Linux kernel process ID (PID) inclusion
106       set of the current recording session to show how an inclusion set
107       works.
108
109       Assume the maximum system PID is 7 for this example.
110
111        1. Initial inclusion set:
112
113               [0] [1] [2] [3] [4] [5] [6] [7]
114
115        2. Command:
116
117               $ lttng track --kernel --pid=3,6,7
118
119           Inclusion set is now:
120
121               [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
122
123        3. Command:
124
125               $ lttng untrack --kernel --pid=7
126
127           Inclusion set is now:
128
129               [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
130
131        4. Command:
132
133               $ lttng track --kernel --pid=1,5
134
135           Inclusion set is now:
136
137               [ ] [1] [ ] [3] [ ] [5] [6] [ ]
138
139       Remove values from an inclusion set with the lttng-untrack(1) command.
140

OPTIONS

142       See lttng(1) for GENERAL OPTIONS.
143
144   Tracing domain
145       One of:
146
147       -k, --kernel
148           Add values to one or more Linux kernel inclusion sets.
149
150       -u, --userspace
151           Add values to one or more user space inclusion sets.
152
153   Recording target
154       -s SESSION, --session=SESSION
155           Add values to one or more inclusion sets of the recording session
156           named SESSION instead of the current recording session.
157
158   Inclusion set selection
159       -p [PID[,PID]...], --pid[=PID[,PID]...]
160           For each PID argument, add PID to the process ID inclusion set of
161           the selected recording session and domain.
162
163           PID is the process ID attribute of a process as seen from the root
164           PID namespace (see pid_namespaces(7)).
165
166           Only available with --kernel option.
167
168       --vpid[=VPID[,VPID]...]
169           For each VPID argument, add VPID to the virtual process ID
170           inclusion set of the selected recording session and domain.
171
172           VPID is the virtual process ID attribute of a process as seen from
173           the PID namespace of the process (see pid_namespaces(7)).
174
175       --uid[=USER[,USER]...]
176           For each USER argument, add USER to the user ID inclusion set of
177           the selected recording session and domain.
178
179           USER is either:
180
181           •   The real user ID (see getuid(3)) of a process as seen from the
182               root user namespace (see user_namespaces(7)).
183
184           •   A user name.
185
186               The connected LTTng session daemon (see lttng-sessiond(8))
187               performs the user name resolution on addition to the user ID
188               inclusion set.
189
190           Only available with --kernel option.
191
192       --vuid[=VUSER[,VUSER]...]
193           For each VUSER argument, add VUSER to the virtual user ID inclusion
194           set of the selected recording session and domain.
195
196           VUSER is either:
197
198           •   The real user ID (see getuid(3)) of a process as seen from the
199               user namespace (see user_namespaces(7)).
200
201           •   A user name.
202
203               The connected LTTng session daemon (see lttng-sessiond(8))
204               performs the user name resolution on addition to the virtual
205               user ID inclusion set.
206
207       --gid[=GROUP[,GROUP]...]
208           For each GROUP argument, add GROUP to the group ID inclusion set of
209           the selected recording session and domain.
210
211           GROUP is either:
212
213           •   The real group ID (see getgid(3)) of a process as seen from the
214               root user namespace (see user_namespaces(7)).
215
216           •   A group name.
217
218               The connected LTTng session daemon (see lttng-sessiond(8))
219               performs the group name resolution on addition to the group ID
220               inclusion set.
221
222           Only available with --kernel option.
223
224       --vgid[=VGROUP[,VGROUP]...]
225           For each VGROUP argument, add VGROUP to the virtual group ID
226           inclusion set of the selected recording session and domain.
227
228           VGROUP is either:
229
230           •   The real group ID (see getgid(3)) of a process as seen from the
231               user namespace (see user_namespaces(7)).
232
233           •   A group name.
234
235               The connected LTTng session daemon (see lttng-sessiond(8))
236               performs the group name resolution on addition to the virtual
237               group ID inclusion set.
238
239   Inclusion set operation
240       -a, --all
241           With one or more empty --pid, --vpid, --uid, --vuid, --gid, and
242           --vgid options: add all the possible values to the selected
243           inclusion sets.
244
245   Program information
246       -h, --help
247           Show help.
248
249           This option attempts to launch /usr/bin/man to view this manual
250           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
251           environment variable.
252
253       --list-options
254           List available command options and quit.
255

EXIT STATUS

257       0
258           Success
259
260       1
261           Command error
262
263       2
264           Undefined command
265
266       3
267           Fatal error
268
269       4
270           Command warning (something went wrong during the command)
271

ENVIRONMENT

273       LTTNG_ABORT_ON_ERROR
274           Set to 1 to abort the process after the first error is encountered.
275
276       LTTNG_HOME
277           Path to the LTTng home directory.
278
279           Defaults to $HOME.
280
281           Useful when the Unix user running the commands has a non-writable
282           home directory.
283
284       LTTNG_MAN_BIN_PATH
285           Absolute path to the manual pager to use to read the LTTng
286           command-line help (with lttng-help(1) or with the --help option)
287           instead of /usr/bin/man.
288
289       LTTNG_SESSION_CONFIG_XSD_PATH
290           Path to the directory containing the session.xsd recording session
291           configuration XML schema.
292
293       LTTNG_SESSIOND_PATH
294           Absolute path to the LTTng session daemon binary (see lttng-
295           sessiond(8)) to spawn from the lttng-create(1) command.
296
297           The --sessiond-path general option overrides this environment
298           variable.
299

FILES

301       $LTTNG_HOME/.lttngrc
302           Unix user’s LTTng runtime configuration.
303
304           This is where LTTng stores the name of the Unix user’s current
305           recording session between executions of lttng(1).  lttng-create(1)
306           and lttng-set-session(1) set the current recording session.
307
308       $LTTNG_HOME/lttng-traces
309           Default output directory of LTTng traces in local and snapshot
310           modes.
311
312           Override this path with the --output option of the lttng-create(1)
313           command.
314
315       $LTTNG_HOME/.lttng
316           Unix user’s LTTng runtime and configuration directory.
317
318       $LTTNG_HOME/.lttng/sessions
319           Default directory containing the Unix user’s saved recording
320           session configurations (see lttng-save(1) and lttng-load(1)).
321
322       /usr/local/etc/lttng/sessions
323           Directory containing the system-wide saved recording session
324           configurations (see lttng-save(1) and lttng-load(1)).
325
326       Note
327           $LTTNG_HOME defaults to the value of the HOME environment variable.
328

EXAMPLES

330       Example 1. Add the PIDs 1728 and 3775 to the Linux kernel process ID
331       inclusion set of the current recording session.
332
333           See the --pid option.
334
335               $ lttng track --kernel --pid=1728,3775
336
337       Example 2. Add the ID of a specific user to the user space virtual user
338       ID inclusion set of a specific recording session.
339
340           See the --vuid and --session options.
341
342               $ lttng track --userspace --session=my-session --vuid=http
343
344       Example 3. Add all the possible group IDs to the Linux kernel group ID
345       inclusion set of the current recording session.
346
347           See the --all and --gid options.
348
349               $ lttng track --kernel --all --gid
350

RESOURCES

352       •   LTTng project website <https://lttng.org>
353
354       •   LTTng documentation <https://lttng.org/docs>
355
356       •   LTTng bug tracker <https://bugs.lttng.org>
357
358       •   Git repositories <https://git.lttng.org>
359
360       •   GitHub organization <https://github.com/lttng>
361
362       •   Continuous integration <https://ci.lttng.org/>
363
364       •   Mailing list <https://lists.lttng.org/> for support and
365           development: lttng-dev@lists.lttng.org
366
367       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
368

COPYRIGHT

370       This program is part of the LTTng-tools project.
371
372       LTTng-tools is distributed under the GNU General Public License
373       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
374       See the LICENSE <https://github.com/lttng/lttng-
375       tools/blob/master/LICENSE> file for details.
376

THANKS

378       Special thanks to Michel Dagenais and the DORSAL laboratory
379       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
380       the LTTng journey.
381
382       Also thanks to the Ericsson teams working on tracing which helped us
383       greatly with detailed bug reports and unusual test cases.
384