lttng-track(1)

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

NAME

6       lttng-track - Add one or more entries to an LTTng resource tracker
7

SYNOPSIS

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

DESCRIPTION

13       The lttng track commands adds one or more entries to a resource
14       tracker.
15
16       A resource tracker is a whitelist of resources. Tracked resources are
17       allowed to emit events, provided those events are targeted by enabled
18       event rules (see lttng-enable-event(1)).
19
20       Tracker entries can be removed from the whitelist with lttng-
21       untrack(1).
22
23       As of this version, the only available tracker is the PID tracker. The
24       process ID (PID) tracker follows one or more process IDs; only the
25       processes with a tracked PID are allowed to emit events. By default,
26       all possible PIDs on the system are tracked: any process may emit
27       enabled events (equivalent of lttng track --pid --all for all domains).
28
29       With the PID tracker, it is possible, for example, to record all system
30       calls called by a given process:
31
32           # lttng enable-event --kernel --all --syscall
33           # lttng track --kernel --pid=2345
34           # lttng start
35
36       If all the PIDs are tracked (i.e. lttng track --pid --all, which is the
37       default state of all domains when creating a tracing session), then
38       using the track command with one or more specific PIDs has the effect
39       of first removing all the PIDs from the whitelist, then adding the
40       specified PIDs.
41
42   Example
43       Assume the maximum system PID is 7 for this example.
44
45       Initial whitelist:
46
47           [0] [1] [2] [3] [4] [5] [6] [7]
48
49       Command:
50
51           $ lttng track --userspace --pid=3,6,7
52
53       Whitelist:
54
55           [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
56
57       Command:
58
59           $ lttng untrack --userspace --pid=7
60
61       Whitelist:
62
63           [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
64
65       Command:
66
67           $ lttng track --userspace --pid=1,5
68
69       Whitelist:
70
71           [ ] [1] [ ] [3] [ ] [5] [6] [ ]
72
73       It should be noted that the PID tracker tracks the numeric process IDs.
74       Should a process with a given ID exit and another process be given this
75       ID, then the latter would also be allowed to emit events.
76
77       See the lttng-untrack(1) for more details about removing entries.
78

OPTIONS

80       General options are described in lttng(1).
81
82   Domain
83       One of:
84
85       -k, --kernel
86           Track resources in the Linux kernel domain.
87
88       -u, --userspace
89           Track resources in the user space domain.
90
91   Target
92       -s SESSION, --session=SESSION
93           Track resources in the tracing session named SESSION instead of the
94           current tracing session.
95
96   Tracking
97       -a, --all
98           Used in conjunction with an empty --pid option: track all process
99           IDs (add all entries to the whitelist).
100
101       -p [PID[,PID]...], --pid[=PID[,PID]...]
102           Track process IDs PID (add them to the current whitelist).
103
104           The PID argument must be omitted when also using the --all option.
105
106   Program information
107       -h, --help
108           Show command help.
109
110           This option, like lttng-help(1), attempts to launch /usr/bin/man to
111           view the command’s man page. The path to the man pager can be
112           overridden by the LTTNG_MAN_BIN_PATH environment variable.
113
114       --list-options
115           List available command options.
116

ENVIRONMENT VARIABLES

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

FILES

144       $LTTNG_HOME/.lttngrc
145           User LTTng runtime configuration.
146
147           This is where the per-user current tracing session is stored
148           between executions of lttng(1). The current tracing session can be
149           set with lttng-set-session(1). See lttng-create(1) for more
150           information about tracing sessions.
151
152       $LTTNG_HOME/lttng-traces
153           Default output directory of LTTng traces. This can be overridden
154           with the --output option of the lttng-create(1) command.
155
156       $LTTNG_HOME/.lttng
157           User LTTng runtime and configuration directory.
158
159       $LTTNG_HOME/.lttng/sessions
160           Default location of saved user tracing sessions (see lttng-save(1)
161           and lttng-load(1)).
162
163       /usr/local/etc/lttng/sessions
164           System-wide location of saved tracing sessions (see lttng-save(1)
165           and lttng-load(1)).
166
167           Note
168           $LTTNG_HOME defaults to $HOME when not explicitly set.
169

EXIT STATUS

171       0
172           Success
173
174       1
175           Command error
176
177       2
178           Undefined command
179
180       3
181           Fatal error
182
183       4
184           Command warning (something went wrong during the command)
185

BUGS

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

RESOURCES

191       ·   LTTng project website <http://lttng.org>
192
193       ·   LTTng documentation <http://lttng.org/docs>
194
195       ·   Git repositories <http://git.lttng.org>
196
197       ·   GitHub organization <http://github.com/lttng>
198
199       ·   Continuous integration <http://ci.lttng.org/>
200
201       ·   Mailing list <http://lists.lttng.org> for support and development:
202           lttng-dev@lists.lttng.org
203
204       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
205

COPYRIGHTS

207       This program is part of the LTTng-tools project.
208
209       LTTng-tools is distributed under the GNU General Public License version
210       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
211       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
212       for details.
213

THANKS

215       Special thanks to Michel Dagenais and the DORSAL laboratory
216       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
217       the LTTng journey.
218
219       Also thanks to the Ericsson teams working on tracing which helped us
220       greatly with detailed bug reports and unusual test cases.
221

AUTHORS

223       LTTng-tools was originally written by Mathieu Desnoyers, Julien
224       Desfossez, and David Goulet. More people have since contributed to it.
225
226       LTTng-tools is currently maintained by Jérémie Galarneau
227       <mailto:jeremie.galarneau@efficios.com>.
228