7 lttng-track - Add one or more property values to an LTTng process tracker
12 Track processes for Linux kernel channels:
15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION']
16 [option:--pid='PID'[,'PID']... | option:--pid option:--all]
17 [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
18 [option:--uid='USER'[,'USER']... | option:--uid option:--all]
19 [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
20 [option:--gid='GROUP'[,'GROUP']... | option:--gid option:--all]
21 [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]
23 Track processes for user space channels:
26 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION']
27 [option:--vpid='PID'[,'PID']... | option:--vpid option:--all]
28 [option:--vuid='USER'[,'USER']... | option:--vuid option:--all]
29 [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all]
34 The `lttng track` commands adds one or more property values to an LTTng
37 A process tracker is a _whitelist_ of values of various process
38 properties. Processes of which all the property values are in the
39 whitelist are said to be _tracked_ and are allowed to emit events,
40 provided those events are also targeted by enabled event rules (see
41 man:lttng-enable-event(1)).
43 You can remove process property values from the whitelist with
46 The available process properties are:
49 Process ID as seen by the Linux kernel (root namespace).
52 User ID or name as seen by the Linux kernel (root namespace).
55 Group ID or name as seen by the Linux kernel (root namespace).
58 Process ID as seen by the traced process.
61 User ID or name as seen by the traced process.
64 Group ID or name as seen by the traced process.
66 With the option:--uid, option:--vuid, option:--gid, and option:--vgid
67 options, when you use one or more user or group names, the LTTng session
68 daemon process (see man:lttng-sessiond(8)) performs the name-to-ID
69 lookup _once_ in the appropriate files in `/etc`.
71 The option:--pid and option:--vpid options specify _numeric_ process
72 IDs. Should a process with a given ID exit and a new process be assigned
73 this same ID, then the latter would also be allowed to emit events.
75 When you create a tracing session (see man:lttng-create(1)), all
76 processes on the system are tracked: any process with any ID, user, and
77 group may emit enabled events. This is the equivalent of using the
78 option:--all option for each process property option.
80 A process is only allowed to emit enabled events when _all_ its property
81 values are part of the tracker's whitelist: its ID, its user ID, and its
84 If all the values of a given property are tracked, which is the default
85 state for each property and for all domains when creating a tracing
86 session, then using the `lttng track` command with one or more specific
87 property values has the effect of first removing all the property values
88 from the whitelist, then adding the specified values.
91 Understanding the whitelist
92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
93 Assume the maximum system PID is 7 for this example.
95 Initial PID whitelist:
97 -------------------------------
98 [0] [1] [2] [3] [4] [5] [6] [7]
99 -------------------------------
105 $ lttng track --kernel --pid=3,6,7
110 -------------------------------
111 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
112 -------------------------------
118 $ lttng untrack --kernel --pid=7
123 -------------------------------
124 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
125 -------------------------------
131 $ lttng track --kernel --pid=1,5
136 -------------------------------
137 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
138 -------------------------------
140 See the man:lttng-untrack(1) for more details about removing property
141 values from the whitelist.
146 Track processes with PID 2394 or 185 as seen from the kernel, any user,
147 and any group for kernel channels:
151 $ lttng track --kernel --pid=2394,185
154 Track processes with any PID, user name `janine` as seen from the
155 traced process, and any group for user space channels:
159 $ lttng track --userspace --vuid=janine
162 Track processes with any PID, user ID 1000 or user name `mireille` as
163 seen from the traced process, and any group for kernel channels:
167 $ lttng track --kernel --vuid=1000,mireille
170 Track processes with any PID, any user, and group name `http` as seen
171 from the traced process for user space channels:
175 $ lttng track --userspace --vgid=http
179 include::common-cmd-options-head.txt[]
186 option:-k, option:--kernel::
187 Track processes for Linux kernel channels.
189 option:-u, option:--userspace::
190 Track processes for user space channels.
195 option:-s 'SESSION', option:--session='SESSION'::
196 Track processes in the tracing session named 'SESSION' instead of
197 the current tracing session.
202 option:-a, option:--all::
203 Following any of the property options below (without an option's
204 argument): add _all_ possible values of this property to the process
207 option:--gid[='GROUP'[,'GROUP']...]::
208 Add group ID or name 'GROUP', as seen by the Linux kernel (root
209 namespace), to the tracker's whitelist.
211 option:--pid[='PID'[,'PID']...]::
212 Add process ID 'PID', as seen by the Linux kernel (root namespace),
213 to the tracker's whitelist.
215 option:--uid[='USER'[,'USER']...]::
216 Add user ID or name 'USER', as seen by the Linux kernel (root
217 namespace), to the tracker's whitelist.
219 option:--vgid[='GROUP'[,'GROUP']...]::
220 Add group ID or name 'GROUP', as seen by the traced process, to the
223 option:--vpid[='PID'[,'PID']...]::
224 Add process ID 'VPID', as seen by the traced process, to the
227 option:--vuid[='USER'[,'USER']...]::
228 Add user ID or name 'USER', as seen by the traced process, to the
231 include::common-cmd-help-options.txt[]
234 include::common-cmd-footer.txt[]
239 man:lttng-untrack(1),