Commit | Line | Data |
---|---|---|
65226554 PP |
1 | lttng-track(1) |
2 | ============== | |
de332339 | 3 | :revdate: 4 March 2020 |
65226554 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
de332339 | 8 | lttng-track - Add one or more values to an LTTng process attribute tracker |
65226554 PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
de332339 JG |
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 | ||
65226554 | 23 | [verse] |
de332339 JG |
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)... | |
65226554 PP |
39 | |
40 | ||
41 | DESCRIPTION | |
42 | ----------- | |
de332339 JG |
43 | The `lttng track` commands adds one or more values to a |
44 | process attribute tracker. | |
65226554 | 45 | |
de332339 JG |
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)). | |
65226554 | 50 | |
de332339 | 51 | Tracker values can be removed from an inclusion set with |
7c1a4458 | 52 | man:lttng-untrack(1). |
65226554 | 53 | |
de332339 | 54 | The available process attribute trackers are: |
9bd01b5e | 55 | |
de332339 JG |
56 | * Process ID (PID) |
57 | * Virtual PID (VPID) | |
58 | * User ID (UID) | |
59 | * Virtual UID (VUID) | |
60 | * Group ID (GID) | |
61 | * Virtual GID (VGID) | |
65226554 | 62 | |
de332339 JG |
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: | |
65226554 | 68 | |
d4f093aa | 69 | [role="term"] |
03c5529d | 70 | ---- |
de332339 JG |
71 | $ lttng track --kernel --pid --vpid --uid --vuid --gid --vgid --all |
72 | $ lttng track --userspace --vpid --vuid --vgid --all | |
03c5529d | 73 | ---- |
65226554 | 74 | |
de332339 JG |
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. | |
65226554 PP |
90 | |
91 | ||
92 | Example | |
93 | ~~~~~~~ | |
de332339 | 94 | Assume the maximum system PID is 7 for this example. |
65226554 | 95 | |
de332339 | 96 | Initial inclusion set: |
65226554 PP |
97 | |
98 | ------------------------------- | |
99 | [0] [1] [2] [3] [4] [5] [6] [7] | |
100 | ------------------------------- | |
101 | ||
102 | Command: | |
103 | ||
d4f093aa | 104 | [role="term"] |
03c5529d | 105 | ---- |
de332339 | 106 | $ lttng track --kernel --pid=3,6,7 |
03c5529d | 107 | ---- |
65226554 | 108 | |
de332339 | 109 | inclusion set: |
65226554 PP |
110 | |
111 | ------------------------------- | |
112 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
113 | ------------------------------- | |
114 | ||
115 | Command: | |
116 | ||
d4f093aa | 117 | [role="term"] |
03c5529d | 118 | ---- |
de332339 | 119 | $ lttng untrack --kernel --pid=7 |
03c5529d | 120 | ---- |
65226554 | 121 | |
de332339 | 122 | inclusion set: |
65226554 PP |
123 | |
124 | ------------------------------- | |
125 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
126 | ------------------------------- | |
127 | ||
128 | Command: | |
129 | ||
d4f093aa | 130 | [role="term"] |
03c5529d | 131 | ---- |
de332339 | 132 | $ lttng track --kernel --pid=1,5 |
03c5529d | 133 | ---- |
65226554 | 134 | |
de332339 | 135 | inclusion set: |
65226554 PP |
136 | |
137 | ------------------------------- | |
138 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
139 | ------------------------------- | |
140 | ||
7c1a4458 | 141 | See the man:lttng-untrack(1) for more details about removing |
de332339 | 142 | values from the inclusion set. |
65226554 PP |
143 | |
144 | ||
145 | include::common-cmd-options-head.txt[] | |
146 | ||
147 | ||
148 | Domain | |
149 | ~~~~~~ | |
150 | One of: | |
151 | ||
152 | option:-k, option:--kernel:: | |
de332339 | 153 | Track process attributes in the Linux kernel domain. |
65226554 PP |
154 | |
155 | option:-u, option:--userspace:: | |
de332339 | 156 | Track process attributes in the user space domain. |
65226554 PP |
157 | |
158 | ||
159 | Target | |
160 | ~~~~~~ | |
59b19c3c | 161 | option:-s 'SESSION', option:--session='SESSION':: |
de332339 | 162 | Track process attributes in the tracing session named 'SESSION' instead of |
65226554 PP |
163 | the current tracing session. |
164 | ||
165 | ||
166 | Tracking | |
167 | ~~~~~~~~ | |
168 | option:-a, option:--all:: | |
de332339 JG |
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). | |
65226554 | 173 | |
59b19c3c | 174 | option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: |
de332339 JG |
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. | |
65226554 PP |
181 | + |
182 | The 'PID' argument must be omitted when also using the option:--all | |
183 | option. | |
184 | ||
de332339 JG |
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)). | |
9bd01b5e | 191 | + |
de332339 | 192 | The 'VPID' argument must be omitted when also using the option:--all |
9bd01b5e JR |
193 | option. |
194 | ||
de332339 JG |
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. | |
9bd01b5e | 206 | + |
de332339 | 207 | The 'USER' argument must be omitted when also using the option:--all |
9bd01b5e JR |
208 | option. |
209 | ||
de332339 JG |
210 | option:--vuid[='USER'[,'USER']...]:: |
211 | Track virtual user ID process attribute values 'USER' (add them to | |
212 | the virtual user ID inclusion set). | |
9bd01b5e | 213 | + |
de332339 JG |
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 | |
9bd01b5e JR |
222 | option. |
223 | ||
de332339 JG |
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. | |
9bd01b5e | 231 | + |
de332339 JG |
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 | |
9bd01b5e JR |
237 | option. |
238 | ||
de332339 JG |
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. | |
9bd01b5e | 249 | + |
de332339 | 250 | The 'GROUP' argument must be omitted when also using the option:--all |
9bd01b5e JR |
251 | option. |
252 | ||
65226554 PP |
253 | |
254 | include::common-cmd-help-options.txt[] | |
255 | ||
256 | ||
257 | include::common-cmd-footer.txt[] | |
258 | ||
259 | ||
260 | SEE ALSO | |
261 | -------- | |
7c1a4458 PP |
262 | man:lttng-untrack(1), |
263 | man:lttng(1) |