lttng-track(1)

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

NAME

6       lttng-track - Add one or more values to an LTTng process attribute
7       tracker
8

SYNOPSIS

10       Add specific process attribute values to a Linux kernel domain tracker:
11
12       lttng [GENERAL OPTIONS] track --kernel
13             (--pid=PID[,PID]... | --vpid=VPID[,VPID]... |
14             --uid=UID[,UID]... | --vuid=VUID[,VUID]... |
15             --gid=GID[,GID]... | --vgid=VGID[,VGID]... )...
16
17       Add all possible process attribute values to a Linux kernel domain
18       tracker:
19
20       lttng [GENERAL OPTIONS] track --kernel
21             --all (--pid | --vpid | --uid |
22             --vuid | --gid | --vgid )...
23
24       Add specific process attribute values to a user space domain tracker:
25
26       lttng [GENERAL OPTIONS] track --userspace
27             (--vpid=VPID[,VPID]... | --vuid=VUID[,VUID]... | --vgid=VGID[,VGID]...)...
28
29       Add all possible process attribute values to a user space domain
30       tracker:
31
32       lttng [GENERAL OPTIONS] track --userspace
33             --all (--vpid | --vgid | --vuid)...
34

DESCRIPTION

36       The lttng track commands adds one or more values to a process attribute
37       tracker.
38
39       A process attribute tracker is an inclusion set of process attributes.
40       Tracked processes are allowed to emit events, provided those events are
41       targeted by enabled event rules (see lttng-enable-event(1)).
42
43       Tracker values can be removed from an inclusion set with lttng-
44       untrack(1).
45
46       The available process attribute trackers are:
47
48       •   Process ID (PID)
49
50       •   Virtual PID (VPID)
51
52       •   User ID (UID)
53
54       •   Virtual UID (VUID)
55
56       •   Group ID (GID)
57
58       •   Virtual GID (VGID)
59
60       A tracker follows one or more process attribute values; only the
61       processes with a tracked value are allowed to emit events. By default,
62       all possible values on the system are tracked: any process may emit
63       enabled events, the equivalent of:
64
65           $ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all
66           $ lttng track --userspace --vpid --vuid --vgid --all
67
68       With the PID tracker, for example, you can record all system calls of a
69       given process:
70
71           $ lttng enable-event --kernel --all --syscall
72           $ lttng track --kernel --pid=2345
73           $ lttng start
74
75       If all the PIDs are tracked (with the --pid and --all options), which
76       is the default state of all domains when creating a tracing session),
77       then using the track command with one or more specific PIDs has the
78       effect of first removing all the PIDs from the inclusion set, then
79       adding the specified PIDs.
80
81   Example
82       Assume the maximum system PID is 7 for this example.
83
84       Initial inclusion set:
85
86           [0] [1] [2] [3] [4] [5] [6] [7]
87
88       Command:
89
90           $ lttng track --kernel --pid=3,6,7
91
92       inclusion set:
93
94           [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
95
96       Command:
97
98           $ lttng untrack --kernel --pid=7
99
100       inclusion set:
101
102           [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
103
104       Command:
105
106           $ lttng track --kernel --pid=1,5
107
108       inclusion set:
109
110           [ ] [1] [ ] [3] [ ] [5] [6] [ ]
111
112       See the lttng-untrack(1) for more details about removing values from
113       the inclusion set.
114

OPTIONS

116       General options are described in lttng(1).
117
118   Domain
119       One of:
120
121       -k, --kernel
122           Track process attributes in the Linux kernel domain.
123
124       -u, --userspace
125           Track process attributes in the user space domain.
126
127   Target
128       -s SESSION, --session=SESSION
129           Track process attributes in the tracing session named SESSION
130           instead of the current tracing session.
131
132   Tracking
133       -a, --all
134           Used in conjunction with a single, empty --pid, --vpid, --uid,
135           --vuid, --gid, or --vgid option: track all possible process
136           attribute values (add all values to the inclusion set).
137
138       -p [PID[,PID]...], --pid[=PID[,PID]...]
139           Track process ID values PID (add them to the process ID inclusion
140           set).
141
142           PID is the process ID attribute of a process as seen from the root
143           PID namespace (see pid_namespaces(7)). It can only be used with the
144           --kernel domain option.
145
146           The PID argument must be omitted when also using the --all option.
147
148       --vpid[=VPID[,VPID]...]
149           Track virtual process ID values VPID (add them to the virtual
150           process ID inclusion set).
151
152           VPID is the virtual process ID attribute of a process as seen from
153           the PID namespace of the process (see pid_namespaces(7)).
154
155           The VPID argument must be omitted when also using the --all option.
156
157       --uid[=USER[,USER]...]
158           Track user ID process attribute values USER (add them to the user
159           ID inclusion set).
160
161           USER is the real user ID (see getuid(3)) of a process as seen from
162           the root user namespace (see user_namespaces(7)). It can only be
163           used with the --kernel domain option.
164
165           USER can also be a user name. The user name resolution is performed
166           by the session daemon (see lttng-sessiond(8)) on addition to the
167           user ID inclusion set.
168
169           The USER argument must be omitted when also using the --all option.
170
171       --vuid[=USER[,USER]...]
172           Track virtual user ID process attribute values USER (add them to
173           the virtual user ID inclusion set).
174
175           USER is the real user ID (see getuid(3)) of a process as seen from
176           the user namespace of the process (see user_namespaces(7)).
177
178           USER can also be a user name. The user name resolution is performed
179           by the session daemon (see lttng-sessiond(8)) on addition to the
180           virtual user ID inclusion set.
181
182           The USER argument must be omitted when also using the --all option.
183
184       --gid[=GROUP[,GROUP]...]
185           Track group ID process attribute values GROUP (add them to the
186           group ID inclusion set).
187
188           GROUP is the real group ID (see getgid(3)) of a process as seen
189           from the root user namespace (see user_namespaces(7)). It can only
190           be used with the --kernel domain option.
191
192           GROUP can also be a group name. The group name resolution is
193           performed by the session daemon (see lttng-sessiond(8)) on addition
194           to the group ID inclusion set.
195
196           The GROUP argument must be omitted when also using the --all
197           option.
198
199       --vgid[=GROUP[,GROUP]...]
200           Track virtual group ID process attribute values GROUP(add them to
201           the virtual group ID inclusion set).
202
203           GROUP is the real group ID (see getgid(3)) of a process as seen
204           from the user namespace of the process (see user_namespaces(7)).
205
206           GROUP can also be a group name. The group name resolution is
207           performed by the session daemon (see lttng-sessiond(8)) on addition
208           to the virtual group ID inclusion set.
209
210           The GROUP argument must be omitted when also using the --all
211           option.
212
213   Program information
214       -h, --help
215           Show command help.
216
217           This option, like lttng-help(1), attempts to launch /usr/bin/man to
218           view the command’s man page. The path to the man pager can be
219           overridden by the LTTNG_MAN_BIN_PATH environment variable.
220
221       --list-options
222           List available command options.
223

ENVIRONMENT VARIABLES

225       LTTNG_ABORT_ON_ERROR
226           Set to 1 to abort the process after the first error is encountered.
227
228       LTTNG_HOME
229           Overrides the $HOME environment variable. Useful when the user
230           running the commands has a non-writable home directory.
231
232       LTTNG_MAN_BIN_PATH
233           Absolute path to the man pager to use for viewing help information
234           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
235
236       LTTNG_SESSION_CONFIG_XSD_PATH
237           Path in which the session.xsd session configuration XML schema may
238           be found.
239
240       LTTNG_SESSIOND_PATH
241           Full session daemon binary path.
242
243           The --sessiond-path option has precedence over this environment
244           variable.
245
246       Note that the lttng-create(1) command can spawn an LTTng session daemon
247       automatically if none is running. See lttng-sessiond(8) for the
248       environment variables influencing the execution of the session daemon.
249

FILES

251       $LTTNG_HOME/.lttngrc
252           User LTTng runtime configuration.
253
254           This is where the per-user current tracing session is stored
255           between executions of lttng(1). The current tracing session can be
256           set with lttng-set-session(1). See lttng-create(1) for more
257           information about tracing sessions.
258
259       $LTTNG_HOME/lttng-traces
260           Default output directory of LTTng traces. This can be overridden
261           with the --output option of the lttng-create(1) command.
262
263       $LTTNG_HOME/.lttng
264           User LTTng runtime and configuration directory.
265
266       $LTTNG_HOME/.lttng/sessions
267           Default location of saved user tracing sessions (see lttng-save(1)
268           and lttng-load(1)).
269
270       /usr/local/etc/lttng/sessions
271           System-wide location of saved tracing sessions (see lttng-save(1)
272           and lttng-load(1)).
273
274           Note
275           $LTTNG_HOME defaults to $HOME when not explicitly set.
276

EXIT STATUS

278       0
279           Success
280
281       1
282           Command error
283
284       2
285           Undefined command
286
287       3
288           Fatal error
289
290       4
291           Command warning (something went wrong during the command)
292

BUGS

294       If you encounter any issue or usability problem, please report it on
295       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
296

RESOURCES

298       •   LTTng project website <https://lttng.org>
299
300       •   LTTng documentation <https://lttng.org/docs>
301
302       •   Git repositories <http://git.lttng.org>
303
304       •   GitHub organization <http://github.com/lttng>
305
306       •   Continuous integration <http://ci.lttng.org/>
307
308       •   Mailing list <http://lists.lttng.org> for support and development:
309           lttng-dev@lists.lttng.org
310
311       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
312

COPYRIGHTS

314       This program is part of the LTTng-tools project.
315
316       LTTng-tools is distributed under the GNU General Public License version
317       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
318       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
319       for details.
320

THANKS

322       Special thanks to Michel Dagenais and the DORSAL laboratory
323       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
324       the LTTng journey.
325
326       Also thanks to the Ericsson teams working on tracing which helped us
327       greatly with detailed bug reports and unusual test cases.
328