Commit | Line | Data |
---|---|---|
65226554 PP |
1 | lttng-track(1) |
2 | ============== | |
3 | ||
4 | ||
5 | NAME | |
6 | ---- | |
4d9f8f6e | 7 | lttng-track - Add one or more property values to an LTTng process tracker |
65226554 PP |
8 | |
9 | ||
10 | SYNOPSIS | |
11 | -------- | |
4d9f8f6e PP |
12 | Track processes for Linux kernel channels: |
13 | ||
14 | [verse] | |
15 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] | |
16 | [option:--pid='PID'[,'PID']... | option:--pid option:--all] | |
17 | [option:--vpid='PID'[,'PID']... | option:--vpid option:--all] | |
18 | [option:--uid='USER'[,'USER']... | option:--uid option:--all] | |
19 | [option:--vuid='USER'[,'USER']... | option:--vuid option:--all] | |
20 | [option:--gid='GROUP'[,'GROUP']... | option:--gid option:--all] | |
21 | [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all] | |
22 | ||
23 | Track processes for user space channels: | |
24 | ||
65226554 | 25 | [verse] |
4d9f8f6e PP |
26 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
27 | [option:--vpid='PID'[,'PID']... | option:--vpid option:--all] | |
28 | [option:--vuid='USER'[,'USER']... | option:--vuid option:--all] | |
29 | [option:--vgid='GROUP'[,'GROUP']... | option:--vgid option:--all] | |
65226554 PP |
30 | |
31 | ||
32 | DESCRIPTION | |
33 | ----------- | |
4d9f8f6e PP |
34 | The `lttng track` commands adds one or more property values to an LTTng |
35 | process tracker. | |
65226554 | 36 | |
4d9f8f6e PP |
37 | A process tracker is a _whitelist_ of values of various process |
38 | properties. Processes of which all the property values are in the | |
39 | whitelist are said to be _tracked_ and are allowed to emit events, | |
40 | provided those events are also targeted by enabled event rules (see | |
41 | man:lttng-enable-event(1)). | |
65226554 | 42 | |
4d9f8f6e | 43 | You can remove process property values from the whitelist with |
7c1a4458 | 44 | man:lttng-untrack(1). |
65226554 | 45 | |
4d9f8f6e | 46 | The available process properties are: |
65226554 | 47 | |
4d9f8f6e PP |
48 | option:--pid:: |
49 | Process ID as seen by the Linux kernel (root namespace). | |
65226554 | 50 | |
4d9f8f6e PP |
51 | option:--uid:: |
52 | User ID or name as seen by the Linux kernel (root namespace). | |
53 | ||
54 | option:--gid:: | |
55 | Group ID or name as seen by the Linux kernel (root namespace). | |
56 | ||
57 | option:--vpid:: | |
58 | Process ID as seen by the traced process. | |
59 | ||
60 | option:--vuid:: | |
61 | User ID or name as seen by the traced process. | |
62 | ||
63 | option:--vgid:: | |
64 | Group ID or name as seen by the traced process. | |
65 | ||
66 | With the option:--uid, option:--vuid, option:--gid, and option:--vgid | |
67 | options, when you use one or more user or group names, the LTTng session | |
68 | daemon process (see man:lttng-sessiond(8)) performs the name-to-ID | |
69 | lookup _once_ in the appropriate files in `/etc`. | |
70 | ||
71 | The option:--pid and option:--vpid options specify _numeric_ process | |
72 | IDs. Should a process with a given ID exit and a new process be assigned | |
73 | this same ID, then the latter would also be allowed to emit events. | |
65226554 | 74 | |
4d9f8f6e PP |
75 | When you create a tracing session (see man:lttng-create(1)), all |
76 | processes on the system are tracked: any process with any ID, user, and | |
77 | group may emit enabled events. This is the equivalent of using the | |
78 | option:--all option for each process property option. | |
65226554 | 79 | |
4d9f8f6e PP |
80 | A process is only allowed to emit enabled events when _all_ its property |
81 | values are part of the tracker's whitelist: its ID, its user ID, and its | |
82 | group ID. | |
65226554 | 83 | |
4d9f8f6e PP |
84 | If all the values of a given property are tracked, which is the default |
85 | state for each property and for all domains when creating a tracing | |
86 | session, then using the `lttng track` command with one or more specific | |
87 | property values has the effect of first removing all the property values | |
88 | from the whitelist, then adding the specified values. | |
89 | ||
90 | ||
91 | Understanding the whitelist | |
92 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
65226554 PP |
93 | Assume the maximum system PID is 7 for this example. |
94 | ||
4d9f8f6e | 95 | Initial PID whitelist: |
65226554 PP |
96 | |
97 | ------------------------------- | |
98 | [0] [1] [2] [3] [4] [5] [6] [7] | |
99 | ------------------------------- | |
100 | ||
101 | Command: | |
102 | ||
d4f093aa | 103 | [role="term"] |
4d9f8f6e PP |
104 | ---- |
105 | $ lttng track --kernel --pid=3,6,7 | |
106 | ---- | |
65226554 PP |
107 | |
108 | Whitelist: | |
109 | ||
110 | ------------------------------- | |
111 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
112 | ------------------------------- | |
113 | ||
114 | Command: | |
115 | ||
d4f093aa | 116 | [role="term"] |
4d9f8f6e PP |
117 | ---- |
118 | $ lttng untrack --kernel --pid=7 | |
119 | ---- | |
65226554 PP |
120 | |
121 | Whitelist: | |
122 | ||
123 | ------------------------------- | |
124 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
125 | ------------------------------- | |
126 | ||
127 | Command: | |
128 | ||
d4f093aa | 129 | [role="term"] |
4d9f8f6e PP |
130 | ---- |
131 | $ lttng track --kernel --pid=1,5 | |
132 | ---- | |
65226554 PP |
133 | |
134 | Whitelist: | |
135 | ||
136 | ------------------------------- | |
137 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
138 | ------------------------------- | |
139 | ||
4d9f8f6e PP |
140 | See the man:lttng-untrack(1) for more details about removing property |
141 | values from the whitelist. | |
65226554 | 142 | |
4d9f8f6e PP |
143 | |
144 | Usage examples | |
145 | ~~~~~~~~~~~~~~ | |
146 | Track processes with PID 2394 or 185 as seen from the kernel, any user, | |
147 | and any group for kernel channels: | |
148 | ||
149 | [role="term"] | |
150 | ---- | |
151 | $ lttng track --kernel --pid=2394,185 | |
152 | ---- | |
153 | ||
154 | Track processes with any PID, user name `janine` as seen from the | |
155 | traced process, and any group for user space channels: | |
156 | ||
157 | [role="term"] | |
158 | ---- | |
159 | $ lttng track --userspace --vuid=janine | |
160 | ---- | |
161 | ||
162 | Track processes with any PID, user ID 1000 or user name `mireille` as | |
163 | seen from the traced process, and any group for kernel channels: | |
164 | ||
165 | [role="term"] | |
166 | ---- | |
167 | $ lttng track --kernel --vuid=1000,mireille | |
168 | ---- | |
169 | ||
170 | Track processes with any PID, any user, and group name `http` as seen | |
171 | from the traced process for user space channels: | |
172 | ||
173 | [role="term"] | |
174 | ---- | |
175 | $ lttng track --userspace --vgid=http | |
176 | ---- | |
65226554 PP |
177 | |
178 | ||
179 | include::common-cmd-options-head.txt[] | |
180 | ||
181 | ||
182 | Domain | |
183 | ~~~~~~ | |
184 | One of: | |
185 | ||
186 | option:-k, option:--kernel:: | |
4d9f8f6e | 187 | Track processes for Linux kernel channels. |
65226554 PP |
188 | |
189 | option:-u, option:--userspace:: | |
4d9f8f6e | 190 | Track processes for user space channels. |
65226554 PP |
191 | |
192 | ||
193 | Target | |
194 | ~~~~~~ | |
28f32bdf | 195 | option:-s 'SESSION', option:--session='SESSION':: |
4d9f8f6e | 196 | Track processes in the tracing session named 'SESSION' instead of |
65226554 PP |
197 | the current tracing session. |
198 | ||
199 | ||
4d9f8f6e PP |
200 | Process property |
201 | ~~~~~~~~~~~~~~~~ | |
65226554 | 202 | option:-a, option:--all:: |
4d9f8f6e PP |
203 | Following any of the property options below (without an option's |
204 | argument): add _all_ possible values of this property to the process | |
205 | tracker's whitelist. | |
206 | ||
207 | option:--gid[='GROUP'[,'GROUP']...]:: | |
208 | Add group ID or name 'GROUP', as seen by the Linux kernel (root | |
209 | namespace), to the tracker's whitelist. | |
210 | ||
211 | option:--pid[='PID'[,'PID']...]:: | |
212 | Add process ID 'PID', as seen by the Linux kernel (root namespace), | |
213 | to the tracker's whitelist. | |
214 | ||
215 | option:--uid[='USER'[,'USER']...]:: | |
216 | Add user ID or name 'USER', as seen by the Linux kernel (root | |
217 | namespace), to the tracker's whitelist. | |
218 | ||
219 | option:--vgid[='GROUP'[,'GROUP']...]:: | |
220 | Add group ID or name 'GROUP', as seen by the traced process, to the | |
221 | tracker's whitelist. | |
65226554 | 222 | |
4d9f8f6e PP |
223 | option:--vpid[='PID'[,'PID']...]:: |
224 | Add process ID 'VPID', as seen by the traced process, to the | |
225 | tracker's whitelist. | |
65226554 | 226 | |
4d9f8f6e PP |
227 | option:--vuid[='USER'[,'USER']...]:: |
228 | Add user ID or name 'USER', as seen by the traced process, to the | |
229 | tracker's whitelist. | |
65226554 PP |
230 | |
231 | include::common-cmd-help-options.txt[] | |
232 | ||
233 | ||
234 | include::common-cmd-footer.txt[] | |
235 | ||
236 | ||
237 | SEE ALSO | |
238 | -------- | |
7c1a4458 PP |
239 | man:lttng-untrack(1), |
240 | man:lttng(1) |