Docs: overhaul of lttng-track(1) and lttng-untrack(1)
[lttng-tools.git] / doc / man / lttng-untrack.1.txt
CommitLineData
882443a6
PP
1lttng-untrack(1)
2================
de332339 3:revdate: 4 March 2020
882443a6
PP
4
5
6NAME
7----
de332339 8lttng-untrack - Remove one or more values from an LTTng process attribute tracker
882443a6
PP
9
10
11SYNOPSIS
12--------
de332339
JG
13Remove 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
21Remove 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
28Remove 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
34Remove all possible process attribute values from a user space domain tracker:
35
882443a6 36[verse]
de332339
JG
37*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *untrack* option:--userspace
38 option:--all (option:--vpid | option:--vgid | option:--vuid)...
882443a6
PP
39
40
41DESCRIPTION
42-----------
de332339
JG
43The `lttng untrack` commands removes one or more values from a
44process attribute tracker.
882443a6 45
7c1a4458 46See man:lttng-track(1) to learn more about LTTng trackers.
882443a6 47
de332339
JG
48The untrack command removes specific process attribute values from a
49tracker's inclusion set. The attributes to remove must have been
50precedently added by man:lttng-track(1). It is also possible to remove
51all the possible values of a process attribute from the inclusion set
52using the option:--all option.
882443a6
PP
53
54
55Example
56~~~~~~~
57One common operation is to create a tracing session
7c1a4458 58(see man:lttng-create(1)), remove all the entries from the PID
de332339 59tracker inclusion set, start tracing, and then manually track PIDs
882443a6
PP
60while tracing is active.
61
62Assume the maximum system PID is 7 for this example.
63
64Command:
65
d4f093aa 66[role="term"]
03c5529d
PP
67----
68$ lttng create
69----
882443a6 70
de332339 71Initial inclusion set:
882443a6
PP
72
73-------------------------------
74[0] [1] [2] [3] [4] [5] [6] [7]
75-------------------------------
76
77Command:
78
d4f093aa 79[role="term"]
03c5529d 80----
de332339 81$ lttng untrack --kernel --pid --all
03c5529d 82----
882443a6 83
de332339 84inclusion set:
882443a6
PP
85
86-------------------------------
87[ ] [ ] [ ] [ ] [ ] [ ] [ ] [ ]
88-------------------------------
89
90Commands:
91
d4f093aa 92[role="term"]
03c5529d 93----
de332339 94$ lttng enable-event --kernel ...
03c5529d
PP
95$ lttng start
96$ # ...
de332339 97$ lttng track --kernel --pid=3,5
03c5529d 98----
882443a6 99
de332339 100inclusion set:
882443a6
PP
101
102-------------------------------
103[ ] [ ] [ ] [3] [ ] [5] [ ] [ ]
104-------------------------------
105
106Command:
107
d4f093aa 108[role="term"]
03c5529d 109----
de332339 110$ lttng track --kernel --pid=2
03c5529d 111----
882443a6 112
de332339 113inclusion set:
882443a6
PP
114
115-------------------------------
116[ ] [ ] [2] [3] [ ] [5] [ ] [ ]
117-------------------------------
118
119
120include::common-cmd-options-head.txt[]
121
122
123Domain
124~~~~~~
125One of:
126
127option:-k, option:--kernel::
de332339 128 Track process attributes in the Linux kernel domain.
882443a6
PP
129
130option:-u, option:--userspace::
de332339 131 Track process attributes in the user space domain.
882443a6
PP
132
133
134Target
135~~~~~~
de332339
JG
136option:-s 'SESSION', option:--session='SESSION'::
137 Untrack process attributes in the tracing session named 'SESSION'
138 instead of the current tracing session.
882443a6
PP
139
140
141Untracking
142~~~~~~~~~~
143option:-a, option:--all::
de332339
JG
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).
882443a6 148
59b19c3c 149option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
de332339
JG
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
154PID namespace_ (see man:pid_namespaces(7)). It can only be used with
155the option:--kernel domain option.
882443a6
PP
156+
157The 'PID' argument must be omitted when also using the option:--all
158option.
159
de332339
JG
160option:--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
165the _PID namespace_ of the process (see man:pid_namespaces(7)).
166+
167The 'VPID' argument must be omitted when also using the option:--all
168option.
169
170option:--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
175from the _root user namespace_ (see man:user_namespaces(7)). It can
176only 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+
181The 'USER' argument must be omitted when also using the option:--all
182option.
183
184option:--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
189from 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+
194The 'USER' argument must be omitted when also using the option:--all
195option.
196
197option:--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
202from the _root user namespace_ (see man:user_namespaces(7)). It can
203only 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+
208The 'GROUP' argument must be omitted when also using the option:--all
209option.
210
211option:--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
216from 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+
221The 'GROUP' argument must be omitted when also using the option:--all
222option.
223
882443a6
PP
224
225include::common-cmd-help-options.txt[]
226
227
228include::common-cmd-footer.txt[]
229
230
231SEE ALSO
232--------
7c1a4458
PP
233man:lttng-track(1),
234man:lttng(1)
This page took 0.062059 seconds and 4 git commands to generate.