Commit | Line | Data |
---|---|---|
882443a6 PP |
1 | lttng-untrack(1) |
2 | ================ | |
e9711845 | 3 | :revdate: 14 June 2021 |
882443a6 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
26f0c779 | 8 | lttng-untrack - Disallow specific processes to record LTTng events |
882443a6 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
26f0c779 | 13 | Disallow 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 | 25 | Disallow 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 | ||
37 | DESCRIPTION | |
38 | ----------- | |
26f0c779 PP |
39 | The `lttng untrack` command disallows one or more processes to record |
40 | LTTng events based on their attributes within: | |
41 | ||
42 | With the option:--session='SESSION' option:: | |
e9711845 | 43 | The recording session named 'SESSION'. |
882443a6 | 44 | |
26f0c779 | 45 | Without 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 | 49 | See man:lttng-concepts(7) to learn more about recording sessions and |
26f0c779 PP |
50 | recording event rules. |
51 | ||
52 | The `untrack` command removes values from _inclusion sets_ of process | |
53 | attributes. See man:lttng-track(1) to learn more about inclusion sets. | |
882443a6 | 54 | |
da39b67c | 55 | See the ``<<examples,EXAMPLES>>'' section below for usage examples. |
882443a6 | 56 | |
f80d5ec6 PP |
57 | |
58 | Inclusion set example | |
59 | ~~~~~~~~~~~~~~~~~~~~~ | |
e9711845 | 60 | A common operation is to create a recording session (see |
f80d5ec6 | 61 | man:lttng-create(1)), remove all the entries from the Linux kernel |
e9711845 PP |
62 | process ID inclusion set, start recording, and then manually add PIDs |
63 | while the recording session is active. | |
882443a6 PP |
64 | |
65 | Assume 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 | 74 | Initial 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 | + |
87 | Inclusion 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 | + |
103 | Inclusion 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 | + |
116 | Inclusion set: | |
117 | + | |
882443a6 PP |
118 | ------------------------------- |
119 | [ ] [ ] [2] [3] [ ] [5] [ ] [ ] | |
120 | ------------------------------- | |
121 | ||
122 | ||
f5511eea | 123 | include::common-lttng-cmd-options-head.txt[] |
882443a6 PP |
124 | |
125 | ||
26f0c779 PP |
126 | Tracing domain |
127 | ~~~~~~~~~~~~~~ | |
882443a6 PP |
128 | One of: |
129 | ||
130 | option:-k, option:--kernel:: | |
26f0c779 | 131 | Remove values from one or more Linux kernel inclusion sets. |
882443a6 PP |
132 | |
133 | option:-u, option:--userspace:: | |
26f0c779 | 134 | Remove values from one or more user space inclusion sets. |
882443a6 PP |
135 | |
136 | ||
26f0c779 PP |
137 | Recording target |
138 | ~~~~~~~~~~~~~~~~ | |
de332339 | 139 | option:-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 |
144 | Inclusion set selection |
145 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
59b19c3c | 146 | option:-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 |
151 | PID namespace (see man:pid_namespaces(7)). | |
882443a6 | 152 | + |
26f0c779 | 153 | Only available with option:--kernel option. |
882443a6 | 154 | |
de332339 | 155 | option:--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 | 160 | the PID namespace of the process (see man:pid_namespaces(7)). |
de332339 JG |
161 | |
162 | option:--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 |
174 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
175 | the user name resolution on removal from the user ID inclusion set. | |
176 | -- | |
de332339 | 177 | + |
26f0c779 | 178 | Only available with option:--kernel option. |
de332339 | 179 | |
26f0c779 PP |
180 | option:--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 |
192 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
193 | the user name resolution on removal from the virtual user ID inclusion | |
194 | set. | |
195 | -- | |
de332339 JG |
196 | |
197 | option:--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 |
209 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
210 | the group name resolution on removal from the group ID inclusion set. | |
211 | -- | |
de332339 | 212 | + |
26f0c779 | 213 | Only available with option:--kernel option. |
de332339 | 214 | |
26f0c779 PP |
215 | option:--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 |
227 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
228 | the group name resolution on removal from the virtual group ID inclusion | |
229 | set. | |
230 | -- | |
231 | ||
232 | ||
233 | Inclusion set operation | |
234 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
235 | option:-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 | 241 | include::common-lttng-cmd-help-options.txt[] |
882443a6 PP |
242 | |
243 | ||
f5511eea PP |
244 | include::common-lttng-cmd-after-options.txt[] |
245 | ||
246 | ||
378cc12a PP |
247 | [[examples]] |
248 | EXAMPLES | |
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 | ==== |
252 | See 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 | ==== |
262 | See 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 | ==== |
273 | See the option:--all and option:--uid options. | |
274 | ||
275 | [role="term"] | |
276 | ---- | |
277 | $ lttng untrack --kernel --all --uid | |
278 | ---- | |
279 | ==== | |
280 | ||
281 | ||
f5511eea | 282 | include::common-footer.txt[] |
882443a6 PP |
283 | |
284 | ||
285 | SEE ALSO | |
286 | -------- | |
26f0c779 | 287 | man:lttng(1), |
af1c4164 PP |
288 | man:lttng-track(1), |
289 | man:lttng-concepts(7) |