Update the remaining manual pages for LTTng-tools 2.13
[lttng-tools.git] / doc / man / lttng-untrack.1.txt
1 lttng-untrack(1)
2 ================
3 :revdate: 1 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
56 Example
57 ~~~~~~~
58 A common operation is to create a tracing session (see
59 man:lttng-create(1)), remove all the entries from the PID tracker
60 inclusion set, start tracing, and then manually track PIDs while the
61 tracing session is active.
62
63 Assume the maximum system PID is 7 for this example.
64
65 . Command:
66 +
67 [role="term"]
68 ----
69 $ lttng create
70 ----
71 +
72 Initial inclusion set:
73 +
74 -------------------------------
75 [0] [1] [2] [3] [4] [5] [6] [7]
76 -------------------------------
77
78 . Command:
79 +
80 [role="term"]
81 ----
82 $ lttng untrack --kernel --pid --all
83 ----
84 +
85 Inclusion set:
86 +
87 -------------------------------
88 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
89 -------------------------------
90
91 . Commands:
92 +
93 [role="term"]
94 ----
95 $ lttng enable-event --kernel ...
96 $ lttng start
97 $ # ...
98 $ lttng track --kernel --pid=3,5
99 ----
100 +
101 Inclusion set:
102 +
103 -------------------------------
104 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
105 -------------------------------
106
107 . Command:
108 +
109 [role="term"]
110 ----
111 $ lttng track --kernel --pid=2
112 ----
113 +
114 Inclusion set:
115 +
116 -------------------------------
117 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
118 -------------------------------
119
120
121 include::common-cmd-options-head.txt[]
122
123
124 Tracing domain
125 ~~~~~~~~~~~~~~
126 One of:
127
128 option:-k, option:--kernel::
129 Remove values from one or more Linux kernel inclusion sets.
130
131 option:-u, option:--userspace::
132 Remove values from one or more user space inclusion sets.
133
134
135 Recording target
136 ~~~~~~~~~~~~~~~~
137 option:-s 'SESSION', option:--session='SESSION'::
138 Remove values from one or more inclusion sets of the tracing session
139 named 'SESSION' instead of the current tracing session.
140
141
142 Inclusion set selection
143 ~~~~~~~~~~~~~~~~~~~~~~~
144 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
145 For each 'PID' argument, remove 'PID' from the process ID inclusion
146 set of the selected tracing session and domain.
147 +
148 'PID' is the process ID attribute of a process as seen from the root
149 PID namespace (see man:pid_namespaces(7)).
150 +
151 Only available with option:--kernel option.
152
153 option:--vpid[='VPID'[,'VPID']...]::
154 For each 'VPID' argument, remove 'VPID' from the virtual process ID
155 inclusion set of the selected tracing session and domain.
156 +
157 'VPID' is the virtual process ID attribute of a process as seen from
158 the PID namespace of the process (see man:pid_namespaces(7)).
159
160 option:--uid[='USER'[,'USER']...]::
161 For each 'USER' argument, remove 'USER' from the user ID inclusion
162 set of the selected tracing session and domain.
163 +
164 'USER' is either:
165 +
166 --
167 * The real user ID (see man:getuid(3)) of a process as seen
168 from the root user namespace (see man:user_namespaces(7)).
169
170 * A user name.
171 +
172 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
173 the user name resolution on removal from the user ID inclusion set.
174 --
175 +
176 Only available with option:--kernel option.
177
178 option:--vuid[='VUSER'[,'VUSER']...]::
179 For each 'VUSER' argument, remove 'VUSER' from the virtual user ID
180 inclusion set of the selected tracing session and domain.
181 +
182 'VUSER' is either:
183 +
184 --
185 * The real user ID (see man:getuid(3)) of a process as seen
186 from the user namespace (see man:user_namespaces(7)).
187
188 * A user name.
189 +
190 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
191 the user name resolution on removal from the virtual user ID inclusion
192 set.
193 --
194
195 option:--gid[='GROUP'[,'GROUP']...]::
196 For each 'GROUP' argument, remove 'GROUP' from the group ID
197 inclusion set of the selected tracing session and domain.
198 +
199 'GROUP' is either:
200 +
201 --
202 * The real group ID (see man:getgid(3)) of a process as seen from the
203 root user namespace (see man:user_namespaces(7)).
204
205 * A group name.
206 +
207 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
208 the group name resolution on removal from the group ID inclusion set.
209 --
210 +
211 Only available with option:--kernel option.
212
213 option:--vgid[='VGROUP'[,'VGROUP']...]::
214 For each 'VGROUP' argument, remove 'VGROUP' from the virtual group
215 ID inclusion set of the selected tracing session and domain.
216 +
217 'VGROUP' is either:
218 +
219 --
220 * The real group ID (see man:getgid(3)) of a process as seen
221 from the user namespace (see man:user_namespaces(7)).
222
223 * A group name.
224 +
225 The connected LTTng session daemon (see man:lttng-sessiond(8)) performs
226 the group name resolution on removal from the virtual group ID inclusion
227 set.
228 --
229
230
231 Inclusion set operation
232 ~~~~~~~~~~~~~~~~~~~~~~~
233 option:-a, option:--all::
234 With one or more empty option:--pid, option:--vpid, option:--uid,
235 option:--vuid, option:--gid, and option:--vgid options: clear the
236 selected inclusion sets.
237
238
239 include::common-cmd-help-options.txt[]
240
241
242 include::common-cmd-footer.txt[]
243
244
245 SEE ALSO
246 --------
247 man:lttng(1),
248 man:lttng-concepts(7),
249 man:lttng-track(1)
This page took 0.039233 seconds and 6 git commands to generate.