Docs: overhaul of lttng-track(1) and lttng-untrack(1)
[lttng-tools.git] / doc / man / lttng-untrack.1.txt
1 lttng-untrack(1)
2 ================
3 :revdate: 4 March 2020
4
5
6 NAME
7 ----
8 lttng-untrack - Remove one or more values from an LTTng process attribute tracker
9
10
11 SYNOPSIS
12 --------
13 Remove specific process attribute values from a Linux kernel domain tracker:
14
15 [verse]
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* 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
21 Remove all possible process attribute values from a Linux kernel domain tracker:
22
23 [verse]
24 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--kernel
25 option:--all (option:--pid | option:--vpid | option:--uid |
26 option:--vuid | option:--gid | option:--vgid )...
27
28 Remove specific process attribute values from a user space domain tracker:
29
30 [verse]
31 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
32 (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
33
34 Remove all possible process attribute values from a user space domain tracker:
35
36 [verse]
37 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
38 option:--all (option:--vpid | option:--vgid | option:--vuid)...
39
40
41 DESCRIPTION
42 -----------
43 The `lttng untrack` commands removes one or more values from a
44 process attribute tracker.
45
46 See man:lttng-track(1) to learn more about LTTng trackers.
47
48 The untrack command removes specific process attribute values from a
49 tracker's inclusion set. The attributes to remove must have been
50 precedently added by man:lttng-track(1). It is also possible to remove
51 all the possible values of a process attribute from the inclusion set
52 using the option:--all option.
53
54
55 Example
56 ~~~~~~~
57 One common operation is to create a tracing session
58 (see man:lttng-create(1)), remove all the entries from the PID
59 tracker inclusion set, start tracing, and then manually track PIDs
60 while tracing is active.
61
62 Assume the maximum system PID is 7 for this example.
63
64 Command:
65
66 [role="term"]
67 ----
68 $ lttng create
69 ----
70
71 Initial inclusion set:
72
73 -------------------------------
74 [0] [1] [2] [3] [4] [5] [6] [7]
75 -------------------------------
76
77 Command:
78
79 [role="term"]
80 ----
81 $ lttng untrack --kernel --pid --all
82 ----
83
84 inclusion set:
85
86 -------------------------------
87 [ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
88 -------------------------------
89
90 Commands:
91
92 [role="term"]
93 ----
94 $ lttng enable-event --kernel ...
95 $ lttng start
96 $ # ...
97 $ lttng track --kernel --pid=3,5
98 ----
99
100 inclusion set:
101
102 -------------------------------
103 [ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
104 -------------------------------
105
106 Command:
107
108 [role="term"]
109 ----
110 $ lttng track --kernel --pid=2
111 ----
112
113 inclusion set:
114
115 -------------------------------
116 [ ] [ ] [2] [3] [ ] [5] [ ] [ ]
117 -------------------------------
118
119
120 include::common-cmd-options-head.txt[]
121
122
123 Domain
124 ~~~~~~
125 One of:
126
127 option:-k, option:--kernel::
128 Track process attributes in the Linux kernel domain.
129
130 option:-u, option:--userspace::
131 Track process attributes in the user space domain.
132
133
134 Target
135 ~~~~~~
136 option:-s 'SESSION', option:--session='SESSION'::
137 Untrack process attributes in the tracing session named 'SESSION'
138 instead of the current tracing session.
139
140
141 Untracking
142 ~~~~~~~~~~
143 option:-a, option:--all::
144 Used in conjunction with a single, empty option:--pid,
145 option:--vpid, option:--uid, option:--vuid, option:--gid,
146 or option:--vgid option: untrack _all_ possible process attribute
147 values (remove all values from the inclusion set).
148
149 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
150 Untrack process ID values 'PID' (remove them from the process ID
151 inclusion set).
152 +
153 'PID' is the process ID attribute of a process as seen from the _root
154 PID namespace_ (see man:pid_namespaces(7)). It can only be used with
155 the option:--kernel domain option.
156 +
157 The 'PID' argument must be omitted when also using the option:--all
158 option.
159
160 option:--vpid[='VPID'[,'VPID']...]::
161 Untrack virtual process ID values 'VPID' (remove them from the
162 virtual process ID inclusion set).
163 +
164 'VPID' is the virtual process ID attribute of a process as seen from
165 the _PID namespace_ of the process (see man:pid_namespaces(7)).
166 +
167 The 'VPID' argument must be omitted when also using the option:--all
168 option.
169
170 option:--uid[='USER'[,'USER']...]::
171 Untrack user ID process attribute values 'USER' (remove them from
172 the user ID inclusion set).
173 +
174 'USER' is the real user ID (see man:getuid(3)) of a process as seen
175 from the _root user namespace_ (see man:user_namespaces(7)). It can
176 only be used with the option:--kernel domain option.
177 +
178 'USER' can also be a user name. No name resolution is performed;
179 'USER' will be matched against the names in the inclusion set.
180 +
181 The 'USER' argument must be omitted when also using the option:--all
182 option.
183
184 option:--vuid[='USER'[,'USER']...]::
185 Untrack virtual user ID process attribute values 'USER' (remove
186 them from the virtual user ID inclusion set).
187 +
188 'USER' is the real user ID (see man:getuid(3)) of a process as seen
189 from the _user namespace_ of the process (see man:user_namespaces(7)).
190 +
191 'USER' can also be a user name. No name resolution is performed;
192 'USER' will be matched against the names in the inclusion set.
193 +
194 The 'USER' argument must be omitted when also using the option:--all
195 option.
196
197 option:--gid[='GROUP'[,'GROUP']...]::
198 Untrack group ID process attribute values 'GROUP' (remove them
199 from the group ID inclusion set).
200 +
201 'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
202 from the _root user namespace_ (see man:user_namespaces(7)). It can
203 only be used with the option:--kernel domain option.
204 +
205 'GROUP' can also be a group name. No name resolution is performed;
206 'GROUP' will be matched against the names in the inclusion set.
207 +
208 The 'GROUP' argument must be omitted when also using the option:--all
209 option.
210
211 option:--vgid[='GROUP'[,'GROUP']...]::
212 Untrack virtual group ID process attribute values 'GROUP'(remove
213 them from the virtual group ID inclusion set).
214 +
215 'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
216 from the _user namespace_ of the process (see man:user_namespaces(7)).
217 +
218 'GROUP' can also be a group name. No name resolution is performed;
219 'GROUP' will be matched against the names in the inclusion set.
220 +
221 The 'GROUP' argument must be omitted when also using the option:--all
222 option.
223
224
225 include::common-cmd-help-options.txt[]
226
227
228 include::common-cmd-footer.txt[]
229
230
231 SEE ALSO
232 --------
233 man:lttng-track(1),
234 man:lttng(1)
This page took 0.048246 seconds and 4 git commands to generate.