lttng-untrack(1)

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

NAME

6       lttng-untrack - Remove one or more values from an LTTng process
7       attribute tracker
8

SYNOPSIS

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

DESCRIPTION

38       The lttng untrack commands removes one or more values from a process
39       attribute tracker.
40
41       See lttng-track(1) to learn more about LTTng trackers.
42
43       The untrack command removes specific process attribute values from a
44       tracker’s inclusion set. The attributes to remove must have been
45       precedently added by lttng-track(1). It is also possible to remove all
46       the possible values of a process attribute from the inclusion set using
47       the --all option.
48
49   Example
50       One common operation is to create a tracing session (see lttng-
51       create(1)), remove all the entries from the PID tracker inclusion set,
52       start tracing, and then manually track PIDs while tracing is active.
53
54       Assume the maximum system PID is 7 for this example.
55
56       Command:
57
58           $ lttng create
59
60       Initial inclusion set:
61
62           [0] [1] [2] [3] [4] [5] [6] [7]
63
64       Command:
65
66           $ lttng untrack --kernel --pid --all
67
68       inclusion set:
69
70           [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
71
72       Commands:
73
74           $ lttng enable-event --kernel ...
75           $ lttng start
76           $ # ...
77           $ lttng track --kernel --pid=3,5
78
79       inclusion set:
80
81           [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
82
83       Command:
84
85           $ lttng track --kernel --pid=2
86
87       inclusion set:
88
89           [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
90

OPTIONS

92       General options are described in lttng(1).
93
94   Domain
95       One of:
96
97       -k, --kernel
98           Track process attributes in the Linux kernel domain.
99
100       -u, --userspace
101           Track process attributes in the user space domain.
102
103   Target
104       -s SESSION, --session=SESSION
105           Untrack process attributes in the tracing session named SESSION
106           instead of the current tracing session.
107
108   Untracking
109       -a, --all
110           Used in conjunction with a single, empty --pid, --vpid, --uid,
111           --vuid, --gid, or --vgid option: untrack all possible process
112           attribute values (remove all values from the inclusion set).
113
114       -p [PID[,PID]...], --pid[=PID[,PID]...]
115           Untrack process ID values PID (remove them from the process ID
116           inclusion set).
117
118           PID is the process ID attribute of a process as seen from the root
119           PID namespace (see pid_namespaces(7)). It can only be used with the
120           --kernel domain option.
121
122           The PID argument must be omitted when also using the --all option.
123
124       --vpid[=VPID[,VPID]...]
125           Untrack virtual process ID values VPID (remove them from the
126           virtual process ID inclusion set).
127
128           VPID is the virtual process ID attribute of a process as seen from
129           the PID namespace of the process (see pid_namespaces(7)).
130
131           The VPID argument must be omitted when also using the --all option.
132
133       --uid[=USER[,USER]...]
134           Untrack user ID process attribute values USER (remove them from the
135           user ID inclusion set).
136
137           USER is the real user ID (see getuid(3)) of a process as seen from
138           the root user namespace (see user_namespaces(7)). It can only be
139           used with the --kernel domain option.
140
141           USER can also be a user name. No name resolution is performed; USER
142           will be matched against the names in the inclusion set.
143
144           The USER argument must be omitted when also using the --all option.
145
146       --vuid[=USER[,USER]...]
147           Untrack virtual user ID process attribute values USER (remove them
148           from the virtual user ID inclusion set).
149
150           USER is the real user ID (see getuid(3)) of a process as seen from
151           the user namespace of the process (see user_namespaces(7)).
152
153           USER can also be a user name. No name resolution is performed; USER
154           will be matched against the names in the inclusion set.
155
156           The USER argument must be omitted when also using the --all option.
157
158       --gid[=GROUP[,GROUP]...]
159           Untrack group ID process attribute values GROUP (remove them from
160           the group ID inclusion set).
161
162           GROUP is the real group ID (see getgid(3)) of a process as seen
163           from the root user namespace (see user_namespaces(7)). It can only
164           be used with the --kernel domain option.
165
166           GROUP can also be a group name. No name resolution is performed;
167           GROUP will be matched against the names in the inclusion set.
168
169           The GROUP argument must be omitted when also using the --all
170           option.
171
172       --vgid[=GROUP[,GROUP]...]
173           Untrack virtual group ID process attribute values GROUP(remove them
174           from the virtual group ID inclusion set).
175
176           GROUP is the real group ID (see getgid(3)) of a process as seen
177           from the user namespace of the process (see user_namespaces(7)).
178
179           GROUP can also be a group name. No name resolution is performed;
180           GROUP will be matched against the names in the inclusion set.
181
182           The GROUP argument must be omitted when also using the --all
183           option.
184
185   Program information
186       -h, --help
187           Show command help.
188
189           This option, like lttng-help(1), attempts to launch /usr/bin/man to
190           view the command’s man page. The path to the man pager can be
191           overridden by the LTTNG_MAN_BIN_PATH environment variable.
192
193       --list-options
194           List available command options.
195

ENVIRONMENT VARIABLES

197       LTTNG_ABORT_ON_ERROR
198           Set to 1 to abort the process after the first error is encountered.
199
200       LTTNG_HOME
201           Overrides the $HOME environment variable. Useful when the user
202           running the commands has a non-writable home directory.
203
204       LTTNG_MAN_BIN_PATH
205           Absolute path to the man pager to use for viewing help information
206           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
207
208       LTTNG_SESSION_CONFIG_XSD_PATH
209           Path in which the session.xsd session configuration XML schema may
210           be found.
211
212       LTTNG_SESSIOND_PATH
213           Full session daemon binary path.
214
215           The --sessiond-path option has precedence over this environment
216           variable.
217
218       Note that the lttng-create(1) command can spawn an LTTng session daemon
219       automatically if none is running. See lttng-sessiond(8) for the
220       environment variables influencing the execution of the session daemon.
221

FILES

223       $LTTNG_HOME/.lttngrc
224           User LTTng runtime configuration.
225
226           This is where the per-user current tracing session is stored
227           between executions of lttng(1). The current tracing session can be
228           set with lttng-set-session(1). See lttng-create(1) for more
229           information about tracing sessions.
230
231       $LTTNG_HOME/lttng-traces
232           Default output directory of LTTng traces. This can be overridden
233           with the --output option of the lttng-create(1) command.
234
235       $LTTNG_HOME/.lttng
236           User LTTng runtime and configuration directory.
237
238       $LTTNG_HOME/.lttng/sessions
239           Default location of saved user tracing sessions (see lttng-save(1)
240           and lttng-load(1)).
241
242       /usr/local/etc/lttng/sessions
243           System-wide location of saved tracing sessions (see lttng-save(1)
244           and lttng-load(1)).
245
246           Note
247           $LTTNG_HOME defaults to $HOME when not explicitly set.
248

EXIT STATUS

250       0
251           Success
252
253       1
254           Command error
255
256       2
257           Undefined command
258
259       3
260           Fatal error
261
262       4
263           Command warning (something went wrong during the command)
264

BUGS

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

RESOURCES

270       •   LTTng project website <https://lttng.org>
271
272       •   LTTng documentation <https://lttng.org/docs>
273
274       •   Git repositories <http://git.lttng.org>
275
276       •   GitHub organization <http://github.com/lttng>
277
278       •   Continuous integration <http://ci.lttng.org/>
279
280       •   Mailing list <http://lists.lttng.org> for support and development:
281           lttng-dev@lists.lttng.org
282
283       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
284

COPYRIGHTS

286       This program is part of the LTTng-tools project.
287
288       LTTng-tools is distributed under the GNU General Public License version
289       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
290       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
291       for details.
292

THANKS

294       Special thanks to Michel Dagenais and the DORSAL laboratory
295       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
296       the LTTng journey.
297
298       Also thanks to the Ericsson teams working on tracing which helped us
299       greatly with detailed bug reports and unusual test cases.
300