scope-exit: Clarify scope_exit noexcept requirement
[lttng-tools.git] / doc / man / lttng-untrack.1.txt
CommitLineData
882443a6
PP
1lttng-untrack(1)
2================
e9711845 3:revdate: 14 June 2021
882443a6
PP
4
5
6NAME
7----
26f0c779 8lttng-untrack - Disallow specific processes to record LTTng events
882443a6
PP
9
10
11SYNOPSIS
12--------
26f0c779 13Disallow specific processes to record Linux kernel events:
de332339
JG
14
15[verse]
26f0c779 16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* 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
JG
20
21[verse]
26f0c779
PP
22*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
23 option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)...
de332339 24
26f0c779 25Disallow specific processes to record user space events:
de332339
JG
26
27[verse]
26f0c779
PP
28*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
29 (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... |
30 option:--vgid=VGROUP[,VGROUP]...)...
de332339 31
882443a6 32[verse]
26f0c779 33*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
de332339 34 option:--all (option:--vpid | option:--vgid | option:--vuid)...
882443a6
PP
35
36
37DESCRIPTION
38-----------
26f0c779
PP
39The `lttng untrack` command disallows one or more processes to record
40LTTng events based on their attributes within:
41
42With the option:--session='SESSION' option::
e9711845 43 The recording session named 'SESSION'.
882443a6 44
26f0c779 45Without the option:--session option::
e9711845
PP
46 The current recording session (see man:lttng-concepts(7) to learn
47 more about the current recording session).
882443a6 48
e9711845 49See man:lttng-concepts(7) to learn more about recording sessions and
26f0c779
PP
50recording event rules.
51
52The `untrack` command removes values from _inclusion sets_ of process
53attributes. See man:lttng-track(1) to learn more about inclusion sets.
882443a6 54
da39b67c 55See the ``<<examples,EXAMPLES>>'' section below for usage examples.
882443a6 56
f80d5ec6
PP
57
58Inclusion set example
59~~~~~~~~~~~~~~~~~~~~~
e9711845 60A common operation is to create a recording session (see
f80d5ec6 61man:lttng-create(1)), remove all the entries from the Linux kernel
e9711845
PP
62process ID inclusion set, start recording, and then manually add PIDs
63while the recording session is active.
882443a6
PP
64
65Assume the maximum system PID is 7 for this example.
66
26f0c779
PP
67. Command:
68+
d4f093aa 69[role="term"]
03c5529d
PP
70----
71$ lttng create
72----
26f0c779 73+
de332339 74Initial inclusion set:
26f0c779 75+
882443a6
PP
76-------------------------------
77[0] [1] [2] [3] [4] [5] [6] [7]
78-------------------------------
79
26f0c779
PP
80. Command:
81+
d4f093aa 82[role="term"]
03c5529d 83----
f80d5ec6 84$ lttng untrack --kernel --all --pid
03c5529d 85----
26f0c779
PP
86+
87Inclusion set:
88+
882443a6
PP
89-------------------------------
90[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
91-------------------------------
92
26f0c779
PP
93. Commands:
94+
d4f093aa 95[role="term"]
03c5529d 96----
de332339 97$ lttng enable-event --kernel ...
03c5529d
PP
98$ lttng start
99$ # ...
de332339 100$ lttng track --kernel --pid=3,5
03c5529d 101----
26f0c779
PP
102+
103Inclusion set:
104+
882443a6
PP
105-------------------------------
106[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
107-------------------------------
108
26f0c779
PP
109. Command:
110+
d4f093aa 111[role="term"]
03c5529d 112----
de332339 113$ lttng track --kernel --pid=2
03c5529d 114----
26f0c779
PP
115+
116Inclusion set:
117+
882443a6
PP
118-------------------------------
119[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
120-------------------------------
121
122
f5511eea 123include::common-lttng-cmd-options-head.txt[]
882443a6
PP
124
125
26f0c779
PP
126Tracing domain
127~~~~~~~~~~~~~~
882443a6
PP
128One of:
129
130option:-k, option:--kernel::
26f0c779 131 Remove values from one or more Linux kernel inclusion sets.
882443a6
PP
132
133option:-u, option:--userspace::
26f0c779 134 Remove values from one or more user space inclusion sets.
882443a6
PP
135
136
26f0c779
PP
137Recording target
138~~~~~~~~~~~~~~~~
de332339 139option:-s 'SESSION', option:--session='SESSION'::
e9711845
PP
140 Remove values from one or more inclusion sets of the recording
141 session named 'SESSION' instead of the current recording session.
882443a6
PP
142
143
26f0c779
PP
144Inclusion set selection
145~~~~~~~~~~~~~~~~~~~~~~~
59b19c3c 146option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
26f0c779 147 For each 'PID' argument, remove 'PID' from the process ID inclusion
e9711845 148 set of the selected recording session and domain.
de332339 149+
26f0c779
PP
150'PID' is the process ID attribute of a process as seen from the root
151PID namespace (see man:pid_namespaces(7)).
882443a6 152+
26f0c779 153Only available with option:--kernel option.
882443a6 154
de332339 155option:--vpid[='VPID'[,'VPID']...]::
26f0c779 156 For each 'VPID' argument, remove 'VPID' from the virtual process ID
e9711845 157 inclusion set of the selected recording session and domain.
de332339
JG
158+
159'VPID' is the virtual process ID attribute of a process as seen from
26f0c779 160the PID namespace of the process (see man:pid_namespaces(7)).
de332339
JG
161
162option:--uid[='USER'[,'USER']...]::
26f0c779 163 For each 'USER' argument, remove 'USER' from the user ID inclusion
e9711845 164 set of the selected recording session and domain.
26f0c779
PP
165+
166'USER' is either:
de332339 167+
26f0c779
PP
168--
169* The real user ID (see man:getuid(3)) of a process as seen
170 from the root user namespace (see man:user_namespaces(7)).
171
172* A user name.
de332339 173+
26f0c779
PP
174The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
175the user name resolution on removal from the user ID inclusion set.
176--
de332339 177+
26f0c779 178Only available with option:--kernel option.
de332339 179
26f0c779
PP
180option:--vuid[='VUSER'[,'VUSER']...]::
181 For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
e9711845 182 inclusion set of the selected recording session and domain.
de332339 183+
26f0c779 184'VUSER' is either:
de332339 185+
26f0c779
PP
186--
187* The real user ID (see man:getuid(3)) of a process as seen
188 from the user namespace (see man:user_namespaces(7)).
189
190* A user name.
de332339 191+
26f0c779
PP
192The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
193the user name resolution on removal from the virtual user ID inclusion
194set.
195--
de332339
JG
196
197option:--gid[='GROUP'[,'GROUP']...]::
26f0c779 198 For each 'GROUP' argument, remove 'GROUP' from the group ID
e9711845 199 inclusion set of the selected recording session and domain.
26f0c779
PP
200+
201'GROUP' is either:
de332339 202+
26f0c779
PP
203--
204* The real group ID (see man:getgid(3)) of a process as seen from the
205 root user namespace (see man:user_namespaces(7)).
206
207* A group name.
de332339 208+
26f0c779
PP
209The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
210the group name resolution on removal from the group ID inclusion set.
211--
de332339 212+
26f0c779 213Only available with option:--kernel option.
de332339 214
26f0c779
PP
215option:--vgid[='VGROUP'[,'VGROUP']...]::
216 For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
e9711845 217 ID inclusion set of the selected recording session and domain.
de332339 218+
26f0c779 219'VGROUP' is either:
de332339 220+
26f0c779
PP
221--
222* The real group ID (see man:getgid(3)) of a process as seen
223 from the user namespace (see man:user_namespaces(7)).
224
225* A group name.
de332339 226+
26f0c779
PP
227The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
228the group name resolution on removal from the virtual group ID inclusion
229set.
230--
231
232
233Inclusion set operation
234~~~~~~~~~~~~~~~~~~~~~~~
235option:-a, option:--all::
236 With one or more empty option:--pid, option:--vpid, option:--uid,
237 option:--vuid, option:--gid, and option:--vgid options: clear the
238 selected inclusion sets.
de332339 239
882443a6 240
f5511eea 241include::common-lttng-cmd-help-options.txt[]
882443a6
PP
242
243
f5511eea
PP
244include::common-lttng-cmd-after-options.txt[]
245
246
378cc12a
PP
247[[examples]]
248EXAMPLES
249--------
e9711845 250.Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current recording session.
378cc12a
PP
251====
252See the option:--pid option.
253
254[role="term"]
255----
256$ lttng untrack --kernel --pid=1728,3775
257----
258====
259
e9711845 260.Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific recording session.
378cc12a
PP
261====
262See the option:--vgid and option:--session options.
263
264[role="term"]
265----
266$ lttng untrack --userspace --session=my-session \
267 --vgid=docker,mysql
268----
269====
270
e9711845 271.Remove all the user IDs from the Linux kernel user ID inclusion set of the current recording session.
378cc12a
PP
272====
273See the option:--all and option:--uid options.
274
275[role="term"]
276----
277$ lttng untrack --kernel --all --uid
278----
279====
280
281
f5511eea 282include::common-footer.txt[]
882443a6
PP
283
284
285SEE ALSO
286--------
26f0c779 287man:lttng(1),
af1c4164
PP
288man:lttng-track(1),
289man:lttng-concepts(7)
This page took 0.060707 seconds and 5 git commands to generate.