Commit | Line | Data |
---|---|---|
65226554 PP |
1 | lttng-track(1) |
2 | ============== | |
26f0c779 | 3 | :revdate: 1 May 2021 |
65226554 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
26f0c779 | 8 | lttng-track - Allow specific processes to record LTTng events |
65226554 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
26f0c779 | 13 | Allow specific processes to record Linux kernel events: |
de332339 JG |
14 | |
15 | [verse] | |
26f0c779 | 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] |
de332339 | 17 | (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... | |
26f0c779 PP |
18 | option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... | |
19 | option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)... | |
de332339 | 20 | |
de332339 | 21 | |
65226554 | 22 | [verse] |
26f0c779 PP |
23 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] |
24 | option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)... | |
de332339 | 25 | |
26f0c779 | 26 | Allow specific processes to record user space events: |
de332339 JG |
27 | |
28 | [verse] | |
26f0c779 PP |
29 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
30 | (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... | | |
31 | option:--vgid=VGROUP[,VGROUP]...)... | |
de332339 JG |
32 | |
33 | [verse] | |
26f0c779 | 34 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
de332339 | 35 | option:--all (option:--vpid | option:--vgid | option:--vuid)... |
65226554 PP |
36 | |
37 | ||
38 | DESCRIPTION | |
39 | ----------- | |
26f0c779 PP |
40 | The `lttng track` command allows one or more processes to record LTTng |
41 | events based on their attributes within: | |
65226554 | 42 | |
26f0c779 PP |
43 | With the option:--session='SESSION' option:: |
44 | The tracing session named 'SESSION'. | |
65226554 | 45 | |
26f0c779 PP |
46 | Without the option:--session option:: |
47 | The current tracing session (see man:lttng-concepts(7) to learn more | |
48 | about the current tracing session). | |
65226554 | 49 | |
26f0c779 PP |
50 | See man:lttng-concepts(7) to learn more about tracing sessions and |
51 | recording event rules. | |
9bd01b5e | 52 | |
26f0c779 PP |
53 | The `track` command adds values to _inclusion sets_ of process |
54 | attributes. The available inclusion sets are, for a given tracing | |
55 | session: | |
65226554 | 56 | |
26f0c779 PP |
57 | With the option:--kernel option:: |
58 | + | |
59 | * Process ID (PID). | |
de332339 | 60 | |
26f0c779 PP |
61 | * Virtual process ID (VPID). |
62 | + | |
63 | This is the PID as seen by the application. | |
65226554 | 64 | |
26f0c779 | 65 | * Unix user ID (UID). |
65226554 | 66 | |
26f0c779 PP |
67 | * Virtual Unix user ID (VUID). |
68 | + | |
69 | This is the UID as seen by the application. | |
70 | ||
71 | * Unix group ID (GID). | |
72 | ||
73 | * Virtual Unix group ID (VGID). | |
74 | + | |
75 | This is the GID as seen by the application. | |
76 | ||
77 | With the option:--userspace option:: | |
78 | + | |
79 | * VPID | |
80 | * VUID | |
81 | * VGID | |
82 | ||
83 | When an event{nbsp}__E__ satisfies all the other explicit and implicit | |
84 | conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if | |
85 | the attributes of the process for which LTTng creates{nbsp}__E__ are | |
86 | *all* part of the inclusion sets of the tracing session and domain | |
87 | of{nbsp}__ER__. | |
88 | ||
89 | By default, on tracing session creation (see man:lttng-create(1)), | |
90 | all processes are allowed to record events. In other words, all the | |
91 | inclusion sets of the tracing session contain all the possible | |
92 | process attribute values. | |
93 | ||
94 | If a given inclusion set{nbsp}__IS__ contains all the possible values | |
95 | (option:--all option), then using the `track` command to add one or more | |
96 | values{nbsp}__V__ to{nbsp}__IS__: | |
97 | ||
98 | . Removes all the values from{nbsp}__IS__. | |
99 | + | |
100 | This effectively makes{nbsp}__IS__ empty. | |
101 | ||
102 | . Adds{nbsp}__V__ to{nbsp}__IS__. | |
103 | ||
104 | Example: with the PID inclusion set, you can record all the system calls | |
105 | of a given process: | |
de332339 JG |
106 | |
107 | [role="term"] | |
108 | ---- | |
109 | $ lttng enable-event --kernel --all --syscall | |
110 | $ lttng track --kernel --pid=2345 | |
111 | $ lttng start | |
112 | ---- | |
113 | ||
26f0c779 PP |
114 | Remove values from an inclusion set with the man:lttng-untrack(1) |
115 | command. | |
65226554 PP |
116 | |
117 | ||
26f0c779 PP |
118 | Inclusion set example |
119 | ~~~~~~~~~~~~~~~~~~~~~ | |
120 | This example operates on the Linux kernel process ID (PID) inclusion set | |
121 | of the current tracing session to show how an inclusion set works. | |
65226554 | 122 | |
26f0c779 | 123 | Assume the maximum system PID is 7 for this example. |
65226554 | 124 | |
26f0c779 PP |
125 | . Initial inclusion set: |
126 | + | |
65226554 PP |
127 | ------------------------------- |
128 | [0] [1] [2] [3] [4] [5] [6] [7] | |
129 | ------------------------------- | |
130 | ||
26f0c779 PP |
131 | . Command: |
132 | + | |
d4f093aa | 133 | [role="term"] |
03c5529d | 134 | ---- |
de332339 | 135 | $ lttng track --kernel --pid=3,6,7 |
03c5529d | 136 | ---- |
26f0c779 PP |
137 | + |
138 | Inclusion set is now: | |
139 | + | |
65226554 PP |
140 | ------------------------------- |
141 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
142 | ------------------------------- | |
143 | ||
26f0c779 PP |
144 | . Command: |
145 | + | |
d4f093aa | 146 | [role="term"] |
03c5529d | 147 | ---- |
de332339 | 148 | $ lttng untrack --kernel --pid=7 |
03c5529d | 149 | ---- |
26f0c779 PP |
150 | + |
151 | Inclusion set is now: | |
152 | + | |
65226554 PP |
153 | ------------------------------- |
154 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
155 | ------------------------------- | |
156 | ||
26f0c779 PP |
157 | . Command: |
158 | + | |
d4f093aa | 159 | [role="term"] |
03c5529d | 160 | ---- |
de332339 | 161 | $ lttng track --kernel --pid=1,5 |
03c5529d | 162 | ---- |
26f0c779 PP |
163 | + |
164 | Inclusion set is now: | |
165 | + | |
65226554 PP |
166 | ------------------------------- |
167 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
168 | ------------------------------- | |
169 | ||
26f0c779 PP |
170 | Remove values from an inclusion set with the man:lttng-untrack(1) |
171 | command. | |
65226554 PP |
172 | |
173 | ||
f5511eea | 174 | include::common-lttng-cmd-options-head.txt[] |
65226554 PP |
175 | |
176 | ||
26f0c779 PP |
177 | Tracing domain |
178 | ~~~~~~~~~~~~~~ | |
65226554 PP |
179 | One of: |
180 | ||
181 | option:-k, option:--kernel:: | |
26f0c779 | 182 | Add values to one or more Linux kernel inclusion sets. |
65226554 PP |
183 | |
184 | option:-u, option:--userspace:: | |
26f0c779 | 185 | Add values to one or more user space inclusion sets. |
65226554 | 186 | |
26f0c779 PP |
187 | Recording target |
188 | ~~~~~~~~~~~~~~~~ | |
59b19c3c | 189 | option:-s 'SESSION', option:--session='SESSION':: |
26f0c779 PP |
190 | Add values to one or more inclusion sets of the tracing session |
191 | named 'SESSION' instead of the current tracing session. | |
65226554 PP |
192 | |
193 | ||
26f0c779 PP |
194 | Inclusion set selection |
195 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
59b19c3c | 196 | option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: |
26f0c779 PP |
197 | For each 'PID' argument, add 'PID' to the process ID inclusion set |
198 | of the selected tracing session and domain. | |
de332339 | 199 | + |
26f0c779 PP |
200 | 'PID' is the process ID attribute of a process as seen from the root |
201 | PID namespace (see man:pid_namespaces(7)). | |
65226554 | 202 | + |
26f0c779 | 203 | Only available with option:--kernel option. |
65226554 | 204 | |
de332339 | 205 | option:--vpid[='VPID'[,'VPID']...]:: |
26f0c779 PP |
206 | For each 'VPID' argument, add 'VPID' to the virtual process ID |
207 | inclusion set of the selected tracing session and domain. | |
de332339 JG |
208 | + |
209 | 'VPID' is the virtual process ID attribute of a process as seen from | |
26f0c779 | 210 | the PID namespace of the process (see man:pid_namespaces(7)). |
9bd01b5e | 211 | |
de332339 | 212 | option:--uid[='USER'[,'USER']...]:: |
26f0c779 PP |
213 | For each 'USER' argument, add 'USER' to the user ID inclusion set of |
214 | the selected tracing session and domain. | |
de332339 | 215 | + |
26f0c779 | 216 | 'USER' is either: |
de332339 | 217 | + |
26f0c779 PP |
218 | -- |
219 | * The real user ID (see man:getuid(3)) of a process as seen | |
220 | from the root user namespace (see man:user_namespaces(7)). | |
221 | ||
222 | * A user name. | |
223 | + | |
224 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs | |
225 | the user name resolution on addition to the user ID inclusion set. | |
226 | -- | |
9bd01b5e | 227 | + |
26f0c779 | 228 | Only available with option:--kernel option. |
9bd01b5e | 229 | |
26f0c779 PP |
230 | option:--vuid[='VUSER'[,'VUSER']...]:: |
231 | For each 'VUSER' argument, add 'VUSER' to the virtual user ID | |
232 | inclusion set of the selected tracing session and domain. | |
9bd01b5e | 233 | + |
26f0c779 | 234 | 'VUSER' is either: |
de332339 | 235 | + |
26f0c779 PP |
236 | -- |
237 | * The real user ID (see man:getuid(3)) of a process as seen | |
238 | from the user namespace (see man:user_namespaces(7)). | |
239 | ||
240 | * A user name. | |
de332339 | 241 | + |
26f0c779 PP |
242 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
243 | the user name resolution on addition to the virtual user ID inclusion | |
244 | set. | |
245 | -- | |
9bd01b5e | 246 | |
de332339 | 247 | option:--gid[='GROUP'[,'GROUP']...]:: |
26f0c779 PP |
248 | For each 'GROUP' argument, add 'GROUP' to the group ID |
249 | inclusion set of the selected tracing session and domain. | |
de332339 | 250 | + |
26f0c779 | 251 | 'GROUP' is either: |
9bd01b5e | 252 | + |
26f0c779 PP |
253 | -- |
254 | * The real group ID (see man:getgid(3)) of a process as seen from the | |
255 | root user namespace (see man:user_namespaces(7)). | |
256 | ||
257 | * A group name. | |
258 | + | |
259 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs | |
260 | the group name resolution on addition to the group ID inclusion set. | |
261 | -- | |
de332339 | 262 | + |
26f0c779 | 263 | Only available with option:--kernel option. |
9bd01b5e | 264 | |
26f0c779 PP |
265 | option:--vgid[='VGROUP'[,'VGROUP']...]:: |
266 | For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID | |
267 | inclusion set of the selected tracing session and domain. | |
de332339 | 268 | + |
26f0c779 | 269 | 'VGROUP' is either: |
de332339 | 270 | + |
26f0c779 PP |
271 | -- |
272 | * The real group ID (see man:getgid(3)) of a process as seen | |
273 | from the user namespace (see man:user_namespaces(7)). | |
274 | ||
275 | * A group name. | |
9bd01b5e | 276 | + |
26f0c779 PP |
277 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
278 | the group name resolution on addition to the virtual group ID inclusion | |
279 | set. | |
280 | -- | |
281 | ||
282 | ||
283 | Inclusion set operation | |
284 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
285 | option:-a, option:--all:: | |
286 | With one or more empty option:--pid, option:--vpid, option:--uid, | |
287 | option:--vuid, option:--gid, and option:--vgid options: add *all* | |
288 | the possible values to the selected inclusion sets. | |
9bd01b5e | 289 | |
65226554 | 290 | |
f5511eea | 291 | include::common-lttng-cmd-help-options.txt[] |
65226554 PP |
292 | |
293 | ||
f5511eea PP |
294 | include::common-lttng-cmd-after-options.txt[] |
295 | ||
296 | ||
297 | include::common-footer.txt[] | |
65226554 PP |
298 | |
299 | ||
300 | SEE ALSO | |
301 | -------- | |
26f0c779 | 302 | man:lttng(1), |
af1c4164 PP |
303 | man:lttng-untrack(1), |
304 | man:lttng-concepts(7) |