lttng-untrack(1)

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

NAME

6       lttng-untrack - Remove one or more entries from an LTTng resource
7       tracker
8

SYNOPSIS

10       lttng [GENERAL OPTIONS] untrack (--kernel | --userspace)
11             [--session=SESSION] (--pid=PID[,PID]... | --all --pid)
12

DESCRIPTION

14       The lttng untrack commands removes one or more entries from a resource
15       tracker.
16
17       See lttng-track(1) to learn more about LTTng trackers.
18
19       The untrack command removes specific resources from a tracker. The
20       resources to remove must have been precedently added by lttng-track(1).
21       It is also possible to remove all the resources from the whitelist
22       using the --all option.
23
24       As of this version, the only available tracker is the PID tracker.
25
26   Example
27       One common operation is to create a tracing session (see lttng-
28       create(1)), remove all the entries from the PID tracker whitelist,
29       start tracing, and then manually track PIDs while tracing is active.
30
31       Assume the maximum system PID is 7 for this example.
32
33       Command:
34
35           $ lttng create
36
37       Initial whitelist:
38
39           [0] [1] [2] [3] [4] [5] [6] [7]
40
41       Command:
42
43           $ lttng untrack --userspace --pid --all
44
45       Whitelist:
46
47           [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
48
49       Commands:
50
51           $ lttng enable-event --userspace ...
52           $ lttng start
53           $ # ...
54           $ lttng track --userspace --pid=3,5
55
56       Whitelist:
57
58           [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
59
60       Command:
61
62           $ lttng track --userspace --pid=2
63
64       Whitelist:
65
66           [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
67

OPTIONS

69       General options are described in lttng(1).
70
71   Domain
72       One of:
73
74       -k, --kernel
75           Untrack resources tracked in the Linux kernel domain.
76
77       -u, --userspace
78           Untrack resources tracked in the user space domain.
79
80   Target
81       -s, --session=SESSION
82           Untrack resources in the tracing session named SESSION instead of
83           the current tracing session.
84
85   Untracking
86       -a, --all
87           Used in conjunction with an empty --pid option: untrack all process
88           IDs (clear the whitelist).
89
90       -p [PID[,PID]...], --pid[=PID[,PID]...]
91           Untrack process IDs PID (remove them from the current whitelist).
92
93           The PID argument must be omitted when also using the --all option.
94
95   Program information
96       -h, --help
97           Show command help.
98
99           This option, like lttng-help(1), attempts to launch /usr/bin/man to
100           view the command’s man page. The path to the man pager can be
101           overridden by the LTTNG_MAN_BIN_PATH environment variable.
102
103       --list-options
104           List available command options.
105

ENVIRONMENT VARIABLES

107       LTTNG_ABORT_ON_ERROR
108           Set to 1 to abort the process after the first error is encountered.
109
110       LTTNG_HOME
111           Overrides the $HOME environment variable. Useful when the user
112           running the commands has a non-writable home directory.
113
114       LTTNG_MAN_BIN_PATH
115           Absolute path to the man pager to use for viewing help information
116           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
117
118       LTTNG_SESSION_CONFIG_XSD_PATH
119           Path in which the session.xsd session configuration XML schema may
120           be found.
121
122       LTTNG_SESSIOND_PATH
123           Full session daemon binary path.
124
125           The --sessiond-path option has precedence over this environment
126           variable.
127
128       Note that the lttng-create(1) command can spawn an LTTng session daemon
129       automatically if none is running. See lttng-sessiond(8) for the
130       environment variables influencing the execution of the session daemon.
131

FILES

133       $LTTNG_HOME/.lttngrc
134           User LTTng runtime configuration.
135
136           This is where the per-user current tracing session is stored
137           between executions of lttng(1). The current tracing session can be
138           set with lttng-set-session(1). See lttng-create(1) for more
139           information about tracing sessions.
140
141       $LTTNG_HOME/lttng-traces
142           Default output directory of LTTng traces. This can be overridden
143           with the --output option of the lttng-create(1) command.
144
145       $LTTNG_HOME/.lttng
146           User LTTng runtime and configuration directory.
147
148       $LTTNG_HOME/.lttng/sessions
149           Default location of saved user tracing sessions (see lttng-save(1)
150           and lttng-load(1)).
151
152       /usr/local/etc/lttng/sessions
153           System-wide location of saved tracing sessions (see lttng-save(1)
154           and lttng-load(1)).
155
156           Note
157           $LTTNG_HOME defaults to $HOME when not explicitly set.
158

EXIT STATUS

160       0
161           Success
162
163       1
164           Command error
165
166       2
167           Undefined command
168
169       3
170           Fatal error
171
172       4
173           Command warning (something went wrong during the command)
174

BUGS

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

RESOURCES

180       ·   LTTng project website <https://lttng.org>
181
182       ·   LTTng documentation <https://lttng.org/docs>
183
184       ·   Git repositories <http://git.lttng.org>
185
186       ·   GitHub organization <http://github.com/lttng>
187
188       ·   Continuous integration <http://ci.lttng.org/>
189
190       ·   Mailing list <http://lists.lttng.org> for support and development:
191           lttng-dev@lists.lttng.org
192
193       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
194

COPYRIGHTS

196       This program is part of the LTTng-tools project.
197
198       LTTng-tools is distributed under the GNU General Public License version
199       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
200       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
201       for details.
202

THANKS

204       Special thanks to Michel Dagenais and the DORSAL laboratory
205       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
206       the LTTng journey.
207
208       Also thanks to the Ericsson teams working on tracing which helped us
209       greatly with detailed bug reports and unusual test cases.
210