lttng-untrack(1): add usage examples
[lttng-tools.git] / doc / man / lttng-untrack.1.txt
1 lttng-untrack(1)
2 ================
3 :revdate: 17 May 2021
4
5
6 NAME
7 ----
8 lttng-untrack - Disallow specific processes to record LTTng events
9
10
11 SYNOPSIS
12 --------
13 Disallow specific processes to record Linux kernel events:
14
15 [verse]
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel [option:--session='SESSION']
17 (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... |
18 option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... |
19 option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)...
20
21 [verse]
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)...
24
25 Disallow specific processes to record user space events:
26
27 [verse]
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]...)...
31
32 [verse]
33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace [option:--session='SESSION']
34 option:--all (option:--vpid | option:--vgid | option:--vuid)...
35
36
37 DESCRIPTION
38 -----------
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::
43 The tracing session named 'SESSION'.
44
45 Without the option:--session option::
46 The current tracing session (see man:lttng-concepts(7) to learn more
47 about the current tracing session).
48
49 See man:lttng-concepts(7) to learn more about tracing sessions and
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.
54
55 See the <<examples,EXAMPLES>> section below for usage examples.
56
57
58 Inclusion set example
59 ~~~~~~~~~~~~~~~~~~~~~
60 A common operation is to create a tracing session (see
61 man:lttng-create(1)), remove all the entries from the Linux kernel
62 process ID inclusion set, start tracing, and then manually add PIDs
63 while the tracing session is active.
64
65 Assume the maximum system PID is 7 for this example.
66
67 . Command:
68 +
69 [role="term"]
70 ----
71 $ lttng create
72 ----
73 +
74 Initial inclusion set:
75 +
76 -------------------------------
77 [0] [1] [2] [3] [4] [5] [6] [7]
78 -------------------------------
79
80 . Command:
81 +
82 [role="term"]
83 ----
84 $ lttng untrack --kernel --all --pid
85 ----
86 +
87 Inclusion set:
88 +
89 -------------------------------
90 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
91 -------------------------------
92
93 . Commands:
94 +
95 [role="term"]
96 ----
97 $ lttng enable-event --kernel ...
98 $ lttng start
99 $ # ...
100 $ lttng track --kernel --pid=3,5
101 ----
102 +
103 Inclusion set:
104 +
105 -------------------------------
106 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
107 -------------------------------
108
109 . Command:
110 +
111 [role="term"]
112 ----
113 $ lttng track --kernel --pid=2
114 ----
115 +
116 Inclusion set:
117 +
118 -------------------------------
119 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
120 -------------------------------
121
122
123 include::common-lttng-cmd-options-head.txt[]
124
125
126 Tracing domain
127 ~~~~~~~~~~~~~~
128 One of:
129
130 option:-k, option:--kernel::
131 Remove values from one or more Linux kernel inclusion sets.
132
133 option:-u, option:--userspace::
134 Remove values from one or more user space inclusion sets.
135
136
137 Recording target
138 ~~~~~~~~~~~~~~~~
139 option:-s 'SESSION', option:--session='SESSION'::
140 Remove values from one or more inclusion sets of the tracing session
141 named 'SESSION' instead of the current tracing session.
142
143
144 Inclusion set selection
145 ~~~~~~~~~~~~~~~~~~~~~~~
146 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
147 For each 'PID' argument, remove 'PID' from the process ID inclusion
148 set of the selected tracing session and domain.
149 +
150 'PID' is the process ID attribute of a process as seen from the root
151 PID namespace (see man:pid_namespaces(7)).
152 +
153 Only available with option:--kernel option.
154
155 option:--vpid[='VPID'[,'VPID']...]::
156 For each 'VPID' argument, remove 'VPID' from the virtual process ID
157 inclusion set of the selected tracing session and domain.
158 +
159 'VPID' is the virtual process ID attribute of a process as seen from
160 the PID namespace of the process (see man:pid_namespaces(7)).
161
162 option:--uid[='USER'[,'USER']...]::
163 For each 'USER' argument, remove 'USER' from the user ID inclusion
164 set of the selected tracing session and domain.
165 +
166 'USER' is either:
167 +
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.
173 +
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 --
177 +
178 Only available with option:--kernel option.
179
180 option:--vuid[='VUSER'[,'VUSER']...]::
181 For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
182 inclusion set of the selected tracing session and domain.
183 +
184 'VUSER' is either:
185 +
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.
191 +
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 --
196
197 option:--gid[='GROUP'[,'GROUP']...]::
198 For each 'GROUP' argument, remove 'GROUP' from the group ID
199 inclusion set of the selected tracing session and domain.
200 +
201 'GROUP' is either:
202 +
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.
208 +
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 --
212 +
213 Only available with option:--kernel option.
214
215 option:--vgid[='VGROUP'[,'VGROUP']...]::
216 For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
217 ID inclusion set of the selected tracing session and domain.
218 +
219 'VGROUP' is either:
220 +
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.
226 +
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.
239
240
241 include::common-lttng-cmd-help-options.txt[]
242
243
244 include::common-lttng-cmd-after-options.txt[]
245
246
247 [[examples]]
248 EXAMPLES
249 --------
250 .Remove the PIDs 1728 and 3775 from the Linux kernel process ID inclusion set of the current tracing session.
251 ====
252 See the option:--pid option.
253
254 [role="term"]
255 ----
256 $ lttng untrack --kernel --pid=1728,3775
257 ----
258 ====
259
260 .Remove the IDs of a specific groups from the user space virtual group ID inclusion set of a specific tracing session.
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
271 .Remove all the user IDs from the Linux kernel user ID inclusion set of the current tracing session.
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
282 include::common-footer.txt[]
283
284
285 SEE ALSO
286 --------
287 man:lttng(1),
288 man:lttng-track(1),
289 man:lttng-concepts(7)
This page took 0.042591 seconds and 6 git commands to generate.