Docs: overhaul of lttng-track(1) and lttng-untrack(1)
[lttng-tools.git] / doc / man / lttng-track.1.txt
CommitLineData
65226554
PP
1lttng-track(1)
2==============
de332339 3:revdate: 4 March 2020
65226554
PP
4
5
6NAME
7----
de332339 8lttng-track - Add one or more values to an LTTng process attribute tracker
65226554
PP
9
10
11SYNOPSIS
12--------
de332339
JG
13Add specific process attribute values to a Linux kernel domain tracker:
14
15[verse]
16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel
17 (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
18 option:--uid=UID[,UID]... | option:--vuid=VUID[,VUID]... |
19 option:--gid=GID[,GID]... | option:--vgid=VGID[,VGID]... )...
20
21Add all possible process attribute values to a Linux kernel domain tracker:
22
65226554 23[verse]
de332339
JG
24*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel
25 option:--all (option:--pid | option:--vpid | option:--uid |
26 option:--vuid | option:--gid | option:--vgid )...
27
28Add specific process attribute values to a user space domain tracker:
29
30[verse]
31*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace
32 (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
33
34Add all possible process attribute values to a user space domain tracker:
35
36[verse]
37*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace
38 option:--all (option:--vpid | option:--vgid | option:--vuid)...
65226554
PP
39
40
41DESCRIPTION
42-----------
de332339
JG
43The `lttng track` commands adds one or more values to a
44process attribute tracker.
65226554 45
de332339
JG
46A process attribute tracker is an _inclusion set_ of process
47attributes. Tracked processes are allowed to emit events, provided
48those events are targeted by enabled event rules (see
49man:lttng-enable-event(1)).
65226554 50
de332339 51Tracker values can be removed from an inclusion set with
7c1a4458 52man:lttng-untrack(1).
65226554 53
de332339 54The available process attribute trackers are:
9bd01b5e 55
de332339
JG
56* Process ID (PID)
57* Virtual PID (VPID)
58* User ID (UID)
59* Virtual UID (VUID)
60* Group ID (GID)
61* Virtual GID (VGID)
65226554 62
de332339
JG
63
64A tracker follows one or more process attribute values; only the
65processes with a tracked value are allowed to emit events. By default,
66all possible values on the system are tracked: any process may emit
67enabled events, the equivalent of:
65226554 68
d4f093aa 69[role="term"]
03c5529d 70----
de332339
JG
71$ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all
72$ lttng track --userspace --vpid --vuid --vgid --all
03c5529d 73----
65226554 74
de332339
JG
75With the PID tracker, for example, you can record all system calls of a
76given process:
77
78[role="term"]
79----
80$ lttng enable-event --kernel --all --syscall
81$ lttng track --kernel --pid=2345
82$ lttng start
83----
84
85If all the PIDs are tracked (with the option:--pid and option:--all
86options), which is the default state of all domains when creating a
87tracing session), then using the track command with one or more
88specific PIDs has the effect of first removing all the PIDs from the
89inclusion set, then adding the specified PIDs.
65226554
PP
90
91
92Example
93~~~~~~~
de332339 94Assume the maximum system PID is 7 for this example.
65226554 95
de332339 96Initial inclusion set:
65226554
PP
97
98-------------------------------
99[0] [1] [2] [3] [4] [5] [6] [7]
100-------------------------------
101
102Command:
103
d4f093aa 104[role="term"]
03c5529d 105----
de332339 106$ lttng track --kernel --pid=3,6,7
03c5529d 107----
65226554 108
de332339 109inclusion set:
65226554
PP
110
111-------------------------------
112[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
113-------------------------------
114
115Command:
116
d4f093aa 117[role="term"]
03c5529d 118----
de332339 119$ lttng untrack --kernel --pid=7
03c5529d 120----
65226554 121
de332339 122inclusion set:
65226554
PP
123
124-------------------------------
125[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
126-------------------------------
127
128Command:
129
d4f093aa 130[role="term"]
03c5529d 131----
de332339 132$ lttng track --kernel --pid=1,5
03c5529d 133----
65226554 134
de332339 135inclusion set:
65226554
PP
136
137-------------------------------
138[ ] [1] [ ] [3] [ ] [5] [6] [ ]
139-------------------------------
140
7c1a4458 141See the man:lttng-untrack(1) for more details about removing
de332339 142values from the inclusion set.
65226554
PP
143
144
145include::common-cmd-options-head.txt[]
146
147
148Domain
149~~~~~~
150One of:
151
152option:-k, option:--kernel::
de332339 153 Track process attributes in the Linux kernel domain.
65226554
PP
154
155option:-u, option:--userspace::
de332339 156 Track process attributes in the user space domain.
65226554
PP
157
158
159Target
160~~~~~~
59b19c3c 161option:-s 'SESSION', option:--session='SESSION'::
de332339 162 Track process attributes in the tracing session named 'SESSION' instead of
65226554
PP
163 the current tracing session.
164
165
166Tracking
167~~~~~~~~
168option:-a, option:--all::
de332339
JG
169 Used in conjunction with a single, empty option:--pid,
170 option:--vpid, option:--uid, option:--vuid, option:--gid,
171 or option:--vgid option: track _all_ possible process attribute
172 values (add all values to the inclusion set).
65226554 173
59b19c3c 174option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
de332339
JG
175 Track process ID values 'PID' (add them to the process ID inclusion
176 set).
177+
178'PID' is the process ID attribute of a process as seen from the _root
179PID namespace_ (see man:pid_namespaces(7)). It can only be used with
180the option:--kernel domain option.
65226554
PP
181+
182The 'PID' argument must be omitted when also using the option:--all
183option.
184
de332339
JG
185option:--vpid[='VPID'[,'VPID']...]::
186 Track virtual process ID values 'VPID' (add them to the virtual
187 process ID inclusion set).
188+
189'VPID' is the virtual process ID attribute of a process as seen from
190the _PID namespace_ of the process (see man:pid_namespaces(7)).
9bd01b5e 191+
de332339 192The 'VPID' argument must be omitted when also using the option:--all
9bd01b5e
JR
193option.
194
de332339
JG
195option:--uid[='USER'[,'USER']...]::
196 Track user ID process attribute values 'USER' (add them to the
197 user ID inclusion set).
198+
199'USER' is the real user ID (see man:getuid(3)) of a process as seen
200from the _root user namespace_ (see man:user_namespaces(7)). It can
201only be used with the option:--kernel domain option.
202+
203'USER' can also be a user name. The user name resolution is performed
204by the session daemon (see man:lttng-sessiond(8)) on addition to the
205user ID inclusion set.
9bd01b5e 206+
de332339 207The 'USER' argument must be omitted when also using the option:--all
9bd01b5e
JR
208option.
209
de332339
JG
210option:--vuid[='USER'[,'USER']...]::
211 Track virtual user ID process attribute values 'USER' (add them to
212 the virtual user ID inclusion set).
9bd01b5e 213+
de332339
JG
214'USER' is the real user ID (see man:getuid(3)) of a process as seen
215from the _user namespace_ of the process (see man:user_namespaces(7)).
216+
217'USER' can also be a user name. The user name resolution is performed
218by the session daemon (see man:lttng-sessiond(8)) on addition to the
219virtual user ID inclusion set.
220+
221The 'USER' argument must be omitted when also using the option:--all
9bd01b5e
JR
222option.
223
de332339
JG
224option:--gid[='GROUP'[,'GROUP']...]::
225 Track group ID process attribute values 'GROUP' (add them to the
226 group ID inclusion set).
227+
228'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
229from the _root user namespace_ (see man:user_namespaces(7)). It can
230only be used with the option:--kernel domain option.
9bd01b5e 231+
de332339
JG
232'GROUP' can also be a group name. The group name resolution is
233performed by the session daemon (see man:lttng-sessiond(8)) on addition
234to the group ID inclusion set.
235+
236The 'GROUP' argument must be omitted when also using the option:--all
9bd01b5e
JR
237option.
238
de332339
JG
239option:--vgid[='GROUP'[,'GROUP']...]::
240 Track virtual group ID process attribute values 'GROUP'(add them to
241 the virtual group ID inclusion set).
242+
243'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
244from the _user namespace_ of the process (see man:user_namespaces(7)).
245+
246'GROUP' can also be a group name. The group name resolution is performed
247by the session daemon (see man:lttng-sessiond(8)) on addition to the
248virtual group ID inclusion set.
9bd01b5e 249+
de332339 250The 'GROUP' argument must be omitted when also using the option:--all
9bd01b5e
JR
251option.
252
65226554
PP
253
254include::common-cmd-help-options.txt[]
255
256
257include::common-cmd-footer.txt[]
258
259
260SEE ALSO
261--------
7c1a4458
PP
262man:lttng-untrack(1),
263man:lttng(1)
This page took 0.059008 seconds and 4 git commands to generate.