lttng-stop(1): add usage examples
[lttng-tools.git] / doc / man / lttng-track.1.txt
CommitLineData
65226554
PP
1lttng-track(1)
2==============
26f0c779 3:revdate: 1 May 2021
65226554
PP
4
5
6NAME
7----
26f0c779 8lttng-track - Allow specific processes to record LTTng events
65226554
PP
9
10
11SYNOPSIS
12--------
26f0c779 13Allow 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 26Allow 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
38DESCRIPTION
39-----------
26f0c779
PP
40The `lttng track` command allows one or more processes to record LTTng
41events based on their attributes within:
65226554 42
26f0c779
PP
43With the option:--session='SESSION' option::
44 The tracing session named 'SESSION'.
65226554 45
26f0c779
PP
46Without 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
50See man:lttng-concepts(7) to learn more about tracing sessions and
51recording event rules.
9bd01b5e 52
26f0c779
PP
53The `track` command adds values to _inclusion sets_ of process
54attributes. The available inclusion sets are, for a given tracing
55session:
65226554 56
26f0c779
PP
57With the option:--kernel option::
58+
59* Process ID (PID).
de332339 60
26f0c779
PP
61* Virtual process ID (VPID).
62+
63This 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+
69This is the UID as seen by the application.
70
71* Unix group ID (GID).
72
73* Virtual Unix group ID (VGID).
74+
75This is the GID as seen by the application.
76
77With the option:--userspace option::
78+
79* VPID
80* VUID
81* VGID
82
83When an event{nbsp}__E__ satisfies all the other explicit and implicit
84conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if
85the attributes of the process for which LTTng creates{nbsp}__E__ are
86*all* part of the inclusion sets of the tracing session and domain
87of{nbsp}__ER__.
88
89By default, on tracing session creation (see man:lttng-create(1)),
90all processes are allowed to record events. In other words, all the
91inclusion sets of the tracing session contain all the possible
92process attribute values.
93
94If 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
96values{nbsp}__V__ to{nbsp}__IS__:
97
98. Removes all the values from{nbsp}__IS__.
99+
100This effectively makes{nbsp}__IS__ empty.
101
102. Adds{nbsp}__V__ to{nbsp}__IS__.
103
104Example: with the PID inclusion set, you can record all the system calls
105of 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
114Remove values from an inclusion set with the man:lttng-untrack(1)
115command.
65226554
PP
116
117
26f0c779
PP
118Inclusion set example
119~~~~~~~~~~~~~~~~~~~~~
120This example operates on the Linux kernel process ID (PID) inclusion set
121of the current tracing session to show how an inclusion set works.
65226554 122
26f0c779 123Assume 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+
138Inclusion 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+
151Inclusion 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+
164Inclusion set is now:
165+
65226554
PP
166-------------------------------
167[ ] [1] [ ] [3] [ ] [5] [6] [ ]
168-------------------------------
169
26f0c779
PP
170Remove values from an inclusion set with the man:lttng-untrack(1)
171command.
65226554
PP
172
173
f5511eea 174include::common-lttng-cmd-options-head.txt[]
65226554
PP
175
176
26f0c779
PP
177Tracing domain
178~~~~~~~~~~~~~~
65226554
PP
179One of:
180
181option:-k, option:--kernel::
26f0c779 182 Add values to one or more Linux kernel inclusion sets.
65226554
PP
183
184option:-u, option:--userspace::
26f0c779 185 Add values to one or more user space inclusion sets.
65226554 186
26f0c779
PP
187Recording target
188~~~~~~~~~~~~~~~~
59b19c3c 189option:-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
194Inclusion set selection
195~~~~~~~~~~~~~~~~~~~~~~~
59b19c3c 196option:-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
201PID namespace (see man:pid_namespaces(7)).
65226554 202+
26f0c779 203Only available with option:--kernel option.
65226554 204
de332339 205option:--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 210the PID namespace of the process (see man:pid_namespaces(7)).
9bd01b5e 211
de332339 212option:--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+
224The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
225the user name resolution on addition to the user ID inclusion set.
226--
9bd01b5e 227+
26f0c779 228Only available with option:--kernel option.
9bd01b5e 229
26f0c779
PP
230option:--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
242The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
243the user name resolution on addition to the virtual user ID inclusion
244set.
245--
9bd01b5e 246
de332339 247option:--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+
259The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
260the group name resolution on addition to the group ID inclusion set.
261--
de332339 262+
26f0c779 263Only available with option:--kernel option.
9bd01b5e 264
26f0c779
PP
265option:--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
277The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
278the group name resolution on addition to the virtual group ID inclusion
279set.
280--
281
282
283Inclusion set operation
284~~~~~~~~~~~~~~~~~~~~~~~
285option:-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 291include::common-lttng-cmd-help-options.txt[]
65226554
PP
292
293
f5511eea
PP
294include::common-lttng-cmd-after-options.txt[]
295
296
297include::common-footer.txt[]
65226554
PP
298
299
300SEE ALSO
301--------
26f0c779 302man:lttng(1),
af1c4164
PP
303man:lttng-untrack(1),
304man:lttng-concepts(7)
This page took 0.047748 seconds and 4 git commands to generate.