3 :revdate: 04 November 2019
8 lttng-track - Add one or more entries to an LTTng resource tracker
14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
15 [option:--session='SESSION'] (option:--pid='PID'[,'PID']... |
16 option:--uid='UID'[,'UID'][,'USERNAME']... |
17 option:--gid='GID'[,'GID'][,'GROUPNAME']... |
18 option:--vpid='VPID'[,'VPID']... |
19 option:--vuid='VUID'[,'VUID'][,'USERNAME']... |
20 option:--vgid='VGID'[,'VGID'][,'GROUPNAME']... |
21 option:--all (option:--pid | option:--uid | option:--gid | option:--vpid | option:--vuid | option:--vgid))
26 The `lttng track` commands adds one or more entries to a
29 A resource tracker is a _whitelist_ of resources. Tracked resources are
30 allowed to emit events, provided those events are targeted by enabled
31 event rules (see man:lttng-enable-event(1)).
33 Tracker entries can be removed from the whitelist with
36 The following tracker are available: PID, UID, GID, VPID, VUID, VGID.
38 A tracker follows one or more IDs; only the processes with a tracked ID are
39 allowed to emit events. By default, all possible IDs on the system are tracked:
40 any process may emit enabled events (equivalent of `lttng track --pid --uid
41 --gid --vpid --vuid --vgid --all` for all domains).
43 With the PID tracker, it is possible, for example, to record all system
44 calls called by a given process:
48 # lttng enable-event --kernel --all --syscall
49 # lttng track --kernel --pid=2345
53 If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
54 the default state of all domains when creating a tracing session), then
55 using the track command with one or more specific PIDs has the effect of
56 first removing all the PIDs from the whitelist, then adding the
62 Assume the maximum system VPID is 7 for this example.
66 -------------------------------
67 [0] [1] [2] [3] [4] [5] [6] [7]
68 -------------------------------
74 $ lttng track --userspace --vpid=3,6,7
79 -------------------------------
80 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
81 -------------------------------
87 $ lttng untrack --userspace --vpid=7
92 -------------------------------
93 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
94 -------------------------------
100 $ lttng track --userspace --vpid=1,5
105 -------------------------------
106 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
107 -------------------------------
109 It should be noted that the VPID tracker tracks the numeric namespaced process
110 IDs. Should a process with a given ID exit and another process be given this ID,
111 then the latter would also be allowed to emit events.
113 See the man:lttng-untrack(1) for more details about removing
117 include::common-cmd-options-head.txt[]
124 option:-k, option:--kernel::
125 Track resources in the Linux kernel domain.
127 option:-u, option:--userspace::
128 Track resources in the user space domain.
133 option:-s 'SESSION', option:--session='SESSION'::
134 Track resources in the tracing session named 'SESSION' instead of
135 the current tracing session.
140 option:-a, option:--all::
141 Used in conjunction with an empty tracker option, e.g: options:--pid track _all_
142 process IDs (add all entries to the whitelist).
144 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
145 Track process IDs 'PID' (add them to the current whitelist).
146 PID is the non-namespaced value for the process.
148 The 'PID' argument must be omitted when also using the option:--all
151 option:-p ['UID'[,'UID']...], option:--uid[='UID'[,'UID'][,'USERNAME']...]::
152 Track process IDs 'UID' (add them to the current whitelist).
153 User name can also be used, name resolution is performed by
155 UID is the non-namespaced user id value for the process.
157 The 'UID' argument must be omitted when also using the option:--all
160 option:-p ['GID'[,'GID']...], option:--gid[='GID'[,'GID'][,'GROUPNAME']...]::
161 Track process IDs 'GID' (add them to the current whitelist).
162 Group name can also be used, name resolution is performed by
164 GID is the non-namespaced group id value for the process.
166 The 'GID' argument must be omitted when also using the option:--all
169 option:-p ['VPID'[,'VPID']...], option:--vpid[='VPID'[,'VPID']...]::
170 Track process IDs 'VPID' (add them to the current whitelist).
171 VPID is the namespaced PID of the process for its current context.
173 The 'VPID' argument must be omitted when also using the option:--all
176 option:-p ['VUID'[,'VUID']...], option:--vuid[='VUID'[,'VUID'][,'USERNAME']...]::
177 Track process IDs 'VUID' (add them to the current whitelist).
178 User name can also be used, name resolution is performed by
180 VUID is the namespaced UID of the process for its current context.
182 The 'VUID' argument must be omitted when also using the option:--all
185 option:-p ['VGID'[,'VGID']...], option:--vgid[='VGID'[,'VGID'][,'GROUPNAME']...]::
186 Track process IDs 'VGID' (add them to the current whitelist).
187 Group name can also be used, name resolution is performed by
189 VGID is the namespaced GID of the process for its current context.
191 The 'VGID' argument must be omitted when also using the option:--all
195 include::common-cmd-help-options.txt[]
198 include::common-cmd-footer.txt[]
203 man:lttng-untrack(1),