Docs: overhaul of lttng-track(1) and lttng-untrack(1)
[lttng-tools.git] / doc / man / lttng-track.1.txt
1 lttng-track(1)
2 ==============
3 :revdate: 4 March 2020
4
5
6 NAME
7 ----
8 lttng-track - Add one or more values to an LTTng process attribute tracker
9
10
11 SYNOPSIS
12 --------
13 Add specific process attribute values to a Linux kernel domain tracker:
14
15 [verse]
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* 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 Add all possible process attribute values to a Linux kernel domain tracker:
22
23 [verse]
24 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel
25 option:--all (option:--pid | option:--vpid | option:--uid |
26 option:--vuid | option:--gid | option:--vgid )...
27
28 Add specific process attribute values to a user space domain tracker:
29
30 [verse]
31 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace
32 (option:--vpid=VPID[,VPID]... | option:--vuid=VUID[,VUID]... | option:--vgid=VGID[,VGID]...)...
33
34 Add all possible process attribute values to a user space domain tracker:
35
36 [verse]
37 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace
38 option:--all (option:--vpid | option:--vgid | option:--vuid)...
39
40
41 DESCRIPTION
42 -----------
43 The `lttng track` commands adds one or more values to a
44 process attribute tracker.
45
46 A process attribute tracker is an _inclusion set_ of process
47 attributes. Tracked processes are allowed to emit events, provided
48 those events are targeted by enabled event rules (see
49 man:lttng-enable-event(1)).
50
51 Tracker values can be removed from an inclusion set with
52 man:lttng-untrack(1).
53
54 The available process attribute trackers are:
55
56 * Process ID (PID)
57 * Virtual PID (VPID)
58 * User ID (UID)
59 * Virtual UID (VUID)
60 * Group ID (GID)
61 * Virtual GID (VGID)
62
63
64 A tracker follows one or more process attribute values; only the
65 processes with a tracked value are allowed to emit events. By default,
66 all possible values on the system are tracked: any process may emit
67 enabled events, the equivalent of:
68
69 [role="term"]
70 ----
71 $ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all
72 $ lttng track --userspace --vpid --vuid --vgid --all
73 ----
74
75 With the PID tracker, for example, you can record all system calls of a
76 given process:
77
78 [role="term"]
79 ----
80 $ lttng enable-event --kernel --all --syscall
81 $ lttng track --kernel --pid=2345
82 $ lttng start
83 ----
84
85 If all the PIDs are tracked (with the option:--pid and option:--all
86 options), which is the default state of all domains when creating a
87 tracing session), then using the track command with one or more
88 specific PIDs has the effect of first removing all the PIDs from the
89 inclusion set, then adding the specified PIDs.
90
91
92 Example
93 ~~~~~~~
94 Assume the maximum system PID is 7 for this example.
95
96 Initial inclusion set:
97
98 -------------------------------
99 [0] [1] [2] [3] [4] [5] [6] [7]
100 -------------------------------
101
102 Command:
103
104 [role="term"]
105 ----
106 $ lttng track --kernel --pid=3,6,7
107 ----
108
109 inclusion set:
110
111 -------------------------------
112 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
113 -------------------------------
114
115 Command:
116
117 [role="term"]
118 ----
119 $ lttng untrack --kernel --pid=7
120 ----
121
122 inclusion set:
123
124 -------------------------------
125 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
126 -------------------------------
127
128 Command:
129
130 [role="term"]
131 ----
132 $ lttng track --kernel --pid=1,5
133 ----
134
135 inclusion set:
136
137 -------------------------------
138 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
139 -------------------------------
140
141 See the man:lttng-untrack(1) for more details about removing
142 values from the inclusion set.
143
144
145 include::common-cmd-options-head.txt[]
146
147
148 Domain
149 ~~~~~~
150 One of:
151
152 option:-k, option:--kernel::
153 Track process attributes in the Linux kernel domain.
154
155 option:-u, option:--userspace::
156 Track process attributes in the user space domain.
157
158
159 Target
160 ~~~~~~
161 option:-s 'SESSION', option:--session='SESSION'::
162 Track process attributes in the tracing session named 'SESSION' instead of
163 the current tracing session.
164
165
166 Tracking
167 ~~~~~~~~
168 option:-a, option:--all::
169 Used in conjunction with a single, empty option:--pid,
170 option:--vpid, option:--uid, option:--vuid, option:--gid,
171 or option:--vgid option: track _all_ possible process attribute
172 values (add all values to the inclusion set).
173
174 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
175 Track process ID values 'PID' (add them to the process ID inclusion
176 set).
177 +
178 'PID' is the process ID attribute of a process as seen from the _root
179 PID namespace_ (see man:pid_namespaces(7)). It can only be used with
180 the option:--kernel domain option.
181 +
182 The 'PID' argument must be omitted when also using the option:--all
183 option.
184
185 option:--vpid[='VPID'[,'VPID']...]::
186 Track virtual process ID values 'VPID' (add them to the virtual
187 process ID inclusion set).
188 +
189 'VPID' is the virtual process ID attribute of a process as seen from
190 the _PID namespace_ of the process (see man:pid_namespaces(7)).
191 +
192 The 'VPID' argument must be omitted when also using the option:--all
193 option.
194
195 option:--uid[='USER'[,'USER']...]::
196 Track user ID process attribute values 'USER' (add them to the
197 user ID inclusion set).
198 +
199 'USER' is the real user ID (see man:getuid(3)) of a process as seen
200 from the _root user namespace_ (see man:user_namespaces(7)). It can
201 only be used with the option:--kernel domain option.
202 +
203 'USER' can also be a user name. The user name resolution is performed
204 by the session daemon (see man:lttng-sessiond(8)) on addition to the
205 user ID inclusion set.
206 +
207 The 'USER' argument must be omitted when also using the option:--all
208 option.
209
210 option:--vuid[='USER'[,'USER']...]::
211 Track virtual user ID process attribute values 'USER' (add them to
212 the virtual user ID inclusion set).
213 +
214 'USER' is the real user ID (see man:getuid(3)) of a process as seen
215 from the _user namespace_ of the process (see man:user_namespaces(7)).
216 +
217 'USER' can also be a user name. The user name resolution is performed
218 by the session daemon (see man:lttng-sessiond(8)) on addition to the
219 virtual user ID inclusion set.
220 +
221 The 'USER' argument must be omitted when also using the option:--all
222 option.
223
224 option:--gid[='GROUP'[,'GROUP']...]::
225 Track group ID process attribute values 'GROUP' (add them to the
226 group ID inclusion set).
227 +
228 'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
229 from the _root user namespace_ (see man:user_namespaces(7)). It can
230 only be used with the option:--kernel domain option.
231 +
232 'GROUP' can also be a group name. The group name resolution is
233 performed by the session daemon (see man:lttng-sessiond(8)) on addition
234 to the group ID inclusion set.
235 +
236 The 'GROUP' argument must be omitted when also using the option:--all
237 option.
238
239 option:--vgid[='GROUP'[,'GROUP']...]::
240 Track virtual group ID process attribute values 'GROUP'(add them to
241 the virtual group ID inclusion set).
242 +
243 'GROUP' is the real group ID (see man:getgid(3)) of a process as seen
244 from the _user namespace_ of the process (see man:user_namespaces(7)).
245 +
246 'GROUP' can also be a group name. The group name resolution is performed
247 by the session daemon (see man:lttng-sessiond(8)) on addition to the
248 virtual group ID inclusion set.
249 +
250 The 'GROUP' argument must be omitted when also using the option:--all
251 option.
252
253
254 include::common-cmd-help-options.txt[]
255
256
257 include::common-cmd-footer.txt[]
258
259
260 SEE ALSO
261 --------
262 man:lttng-untrack(1),
263 man:lttng(1)
This page took 0.048904 seconds and 4 git commands to generate.