| 1 | lttng-track(1) |
| 2 | ============== |
| 3 | :revdate: 14 June 2021 |
| 4 | |
| 5 | |
| 6 | NAME |
| 7 | ---- |
| 8 | lttng-track - Allow specific processes to record LTTng events |
| 9 | |
| 10 | |
| 11 | SYNOPSIS |
| 12 | -------- |
| 13 | Allow specific processes to record Linux kernel events: |
| 14 | |
| 15 | [verse] |
| 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] |
| 17 | (option:--pid=PID[,PID]... | option:--vpid=VPID[,VPID]... | |
| 18 | option:--uid=UID[,UID]... | option:--vuid=VUSER[,VUSER]... | |
| 19 | option:--gid=GID[,GID]... | option:--vgid=VGROUP[,VGROUP]...)... |
| 20 | |
| 21 | |
| 22 | [verse] |
| 23 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--kernel [option:--session='SESSION'] |
| 24 | option:--all (option:--pid | option:--vpid | option:--uid | option:--vuid | option:--gid | option:--vgid)... |
| 25 | |
| 26 | Allow specific processes to record user space events: |
| 27 | |
| 28 | [verse] |
| 29 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
| 30 | (option:--vpid=VPID[,VPID]... | option:--vuid=VUSER[,VUSER]... | |
| 31 | option:--vgid=VGROUP[,VGROUP]...)... |
| 32 | |
| 33 | [verse] |
| 34 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* option:--userspace [option:--session='SESSION'] |
| 35 | option:--all (option:--vpid | option:--vgid | option:--vuid)... |
| 36 | |
| 37 | |
| 38 | DESCRIPTION |
| 39 | ----------- |
| 40 | The `lttng track` command allows one or more processes to record LTTng |
| 41 | events based on their attributes within: |
| 42 | |
| 43 | With the option:--session='SESSION' option:: |
| 44 | The recording session named 'SESSION'. |
| 45 | |
| 46 | Without the option:--session option:: |
| 47 | The current recording session (see man:lttng-concepts(7) to learn |
| 48 | more about the current recording session). |
| 49 | |
| 50 | See man:lttng-concepts(7) to learn more about recording sessions and |
| 51 | recording event rules. |
| 52 | |
| 53 | The `track` command adds values to _inclusion sets_ of process |
| 54 | attributes. The available inclusion sets are, for a given recording |
| 55 | session: |
| 56 | |
| 57 | With the option:--kernel option:: |
| 58 | + |
| 59 | * Process ID (PID). |
| 60 | |
| 61 | * Virtual process ID (VPID). |
| 62 | + |
| 63 | This is the PID as seen by the application. |
| 64 | |
| 65 | * Unix user ID (UID). |
| 66 | |
| 67 | * Virtual Unix user ID (VUID). |
| 68 | + |
| 69 | This is the UID as seen by the application. |
| 70 | |
| 71 | * Unix group ID (GID). |
| 72 | |
| 73 | * Virtual Unix group ID (VGID). |
| 74 | + |
| 75 | This is the GID as seen by the application. |
| 76 | |
| 77 | With the option:--userspace option:: |
| 78 | + |
| 79 | * VPID |
| 80 | * VUID |
| 81 | * VGID |
| 82 | |
| 83 | When an event{nbsp}__E__ satisfies all the other explicit and implicit |
| 84 | conditions of an event rule{nbsp}__ER__, __ER__ matches{nbsp}__E__ if |
| 85 | the attributes of the process for which LTTng creates{nbsp}__E__ are |
| 86 | *all* part of the inclusion sets of the recording session and domain |
| 87 | of{nbsp}__ER__. |
| 88 | |
| 89 | By default, on recording session creation (see man:lttng-create(1)), |
| 90 | all processes are allowed to record events. In other words, all the |
| 91 | inclusion sets of the recording session contain all the possible |
| 92 | process attribute values. |
| 93 | |
| 94 | If a given inclusion set{nbsp}__IS__ contains all the possible values |
| 95 | (option:--all option), then using the `track` command to add one or more |
| 96 | values{nbsp}__V__ to{nbsp}__IS__: |
| 97 | |
| 98 | . Removes all the values from{nbsp}__IS__. |
| 99 | + |
| 100 | This effectively makes{nbsp}__IS__ empty. |
| 101 | |
| 102 | . Adds{nbsp}__V__ to{nbsp}__IS__. |
| 103 | |
| 104 | Example: with the PID inclusion set, you can record all the system calls |
| 105 | of a given process: |
| 106 | |
| 107 | [role="term"] |
| 108 | ---- |
| 109 | $ lttng enable-event --kernel --all --syscall |
| 110 | $ lttng track --kernel --pid=2345 |
| 111 | $ lttng start |
| 112 | ---- |
| 113 | |
| 114 | See the ``<<examples,EXAMPLES>>'' section below for usage examples. |
| 115 | |
| 116 | Remove values from an inclusion set with the man:lttng-untrack(1) |
| 117 | command. |
| 118 | |
| 119 | |
| 120 | Inclusion set example |
| 121 | ~~~~~~~~~~~~~~~~~~~~~ |
| 122 | This example operates on the Linux kernel process ID (PID) inclusion set |
| 123 | of the current recording session to show how an inclusion set works. |
| 124 | |
| 125 | Assume the maximum system PID is 7 for this example. |
| 126 | |
| 127 | . Initial inclusion set: |
| 128 | + |
| 129 | ------------------------------- |
| 130 | [0] [1] [2] [3] [4] [5] [6] [7] |
| 131 | ------------------------------- |
| 132 | |
| 133 | . Command: |
| 134 | + |
| 135 | [role="term"] |
| 136 | ---- |
| 137 | $ lttng track --kernel --pid=3,6,7 |
| 138 | ---- |
| 139 | + |
| 140 | Inclusion set is now: |
| 141 | + |
| 142 | ------------------------------- |
| 143 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] |
| 144 | ------------------------------- |
| 145 | |
| 146 | . Command: |
| 147 | + |
| 148 | [role="term"] |
| 149 | ---- |
| 150 | $ lttng untrack --kernel --pid=7 |
| 151 | ---- |
| 152 | + |
| 153 | Inclusion set is now: |
| 154 | + |
| 155 | ------------------------------- |
| 156 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] |
| 157 | ------------------------------- |
| 158 | |
| 159 | . Command: |
| 160 | + |
| 161 | [role="term"] |
| 162 | ---- |
| 163 | $ lttng track --kernel --pid=1,5 |
| 164 | ---- |
| 165 | + |
| 166 | Inclusion set is now: |
| 167 | + |
| 168 | ------------------------------- |
| 169 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] |
| 170 | ------------------------------- |
| 171 | |
| 172 | Remove values from an inclusion set with the man:lttng-untrack(1) |
| 173 | command. |
| 174 | |
| 175 | |
| 176 | include::common-lttng-cmd-options-head.txt[] |
| 177 | |
| 178 | |
| 179 | Tracing domain |
| 180 | ~~~~~~~~~~~~~~ |
| 181 | One of: |
| 182 | |
| 183 | option:-k, option:--kernel:: |
| 184 | Add values to one or more Linux kernel inclusion sets. |
| 185 | |
| 186 | option:-u, option:--userspace:: |
| 187 | Add values to one or more user space inclusion sets. |
| 188 | |
| 189 | Recording target |
| 190 | ~~~~~~~~~~~~~~~~ |
| 191 | option:-s 'SESSION', option:--session='SESSION':: |
| 192 | Add values to one or more inclusion sets of the recording session |
| 193 | named 'SESSION' instead of the current recording session. |
| 194 | |
| 195 | |
| 196 | Inclusion set selection |
| 197 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 198 | option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: |
| 199 | For each 'PID' argument, add 'PID' to the process ID inclusion set |
| 200 | of the selected recording session and domain. |
| 201 | + |
| 202 | 'PID' is the process ID attribute of a process as seen from the root |
| 203 | PID namespace (see man:pid_namespaces(7)). |
| 204 | + |
| 205 | Only available with option:--kernel option. |
| 206 | |
| 207 | option:--vpid[='VPID'[,'VPID']...]:: |
| 208 | For each 'VPID' argument, add 'VPID' to the virtual process ID |
| 209 | inclusion set of the selected recording session and domain. |
| 210 | + |
| 211 | 'VPID' is the virtual process ID attribute of a process as seen from |
| 212 | the PID namespace of the process (see man:pid_namespaces(7)). |
| 213 | |
| 214 | option:--uid[='USER'[,'USER']...]:: |
| 215 | For each 'USER' argument, add 'USER' to the user ID inclusion set of |
| 216 | the selected recording session and domain. |
| 217 | + |
| 218 | 'USER' is either: |
| 219 | + |
| 220 | -- |
| 221 | * The real user ID (see man:getuid(3)) of a process as seen |
| 222 | from the root user namespace (see man:user_namespaces(7)). |
| 223 | |
| 224 | * A user name. |
| 225 | + |
| 226 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 227 | the user name resolution on addition to the user ID inclusion set. |
| 228 | -- |
| 229 | + |
| 230 | Only available with option:--kernel option. |
| 231 | |
| 232 | option:--vuid[='VUSER'[,'VUSER']...]:: |
| 233 | For each 'VUSER' argument, add 'VUSER' to the virtual user ID |
| 234 | inclusion set of the selected recording session and domain. |
| 235 | + |
| 236 | 'VUSER' is either: |
| 237 | + |
| 238 | -- |
| 239 | * The real user ID (see man:getuid(3)) of a process as seen |
| 240 | from the user namespace (see man:user_namespaces(7)). |
| 241 | |
| 242 | * A user name. |
| 243 | + |
| 244 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 245 | the user name resolution on addition to the virtual user ID inclusion |
| 246 | set. |
| 247 | -- |
| 248 | |
| 249 | option:--gid[='GROUP'[,'GROUP']...]:: |
| 250 | For each 'GROUP' argument, add 'GROUP' to the group ID |
| 251 | inclusion set of the selected recording session and domain. |
| 252 | + |
| 253 | 'GROUP' is either: |
| 254 | + |
| 255 | -- |
| 256 | * The real group ID (see man:getgid(3)) of a process as seen from the |
| 257 | root user namespace (see man:user_namespaces(7)). |
| 258 | |
| 259 | * A group name. |
| 260 | + |
| 261 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 262 | the group name resolution on addition to the group ID inclusion set. |
| 263 | -- |
| 264 | + |
| 265 | Only available with option:--kernel option. |
| 266 | |
| 267 | option:--vgid[='VGROUP'[,'VGROUP']...]:: |
| 268 | For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID |
| 269 | inclusion set of the selected recording session and domain. |
| 270 | + |
| 271 | 'VGROUP' is either: |
| 272 | + |
| 273 | -- |
| 274 | * The real group ID (see man:getgid(3)) of a process as seen |
| 275 | from the user namespace (see man:user_namespaces(7)). |
| 276 | |
| 277 | * A group name. |
| 278 | + |
| 279 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 280 | the group name resolution on addition to the virtual group ID inclusion |
| 281 | set. |
| 282 | -- |
| 283 | |
| 284 | |
| 285 | Inclusion set operation |
| 286 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 287 | option:-a, option:--all:: |
| 288 | With one or more empty option:--pid, option:--vpid, option:--uid, |
| 289 | option:--vuid, option:--gid, and option:--vgid options: add *all* |
| 290 | the possible values to the selected inclusion sets. |
| 291 | |
| 292 | |
| 293 | include::common-lttng-cmd-help-options.txt[] |
| 294 | |
| 295 | |
| 296 | include::common-lttng-cmd-after-options.txt[] |
| 297 | |
| 298 | |
| 299 | [[examples]] |
| 300 | EXAMPLES |
| 301 | -------- |
| 302 | .Add the PIDs 1728 and 3775 to the Linux kernel process ID inclusion set of the current recording session. |
| 303 | ==== |
| 304 | See the option:--pid option. |
| 305 | |
| 306 | [role="term"] |
| 307 | ---- |
| 308 | $ lttng track --kernel --pid=1728,3775 |
| 309 | ---- |
| 310 | ==== |
| 311 | |
| 312 | .Add the ID of a specific user to the user space virtual user ID inclusion set of a specific recording session. |
| 313 | ==== |
| 314 | See the option:--vuid and option:--session options. |
| 315 | |
| 316 | [role="term"] |
| 317 | ---- |
| 318 | $ lttng track --userspace --session=my-session --vuid=http |
| 319 | ---- |
| 320 | ==== |
| 321 | |
| 322 | .Add all the possible group IDs to the Linux kernel group ID inclusion set of the current recording session. |
| 323 | ==== |
| 324 | See the option:--all and option:--gid options. |
| 325 | |
| 326 | [role="term"] |
| 327 | ---- |
| 328 | $ lttng track --kernel --all --gid |
| 329 | ---- |
| 330 | ==== |
| 331 | |
| 332 | |
| 333 | include::common-footer.txt[] |
| 334 | |
| 335 | |
| 336 | SEE ALSO |
| 337 | -------- |
| 338 | man:lttng(1), |
| 339 | man:lttng-untrack(1), |
| 340 | man:lttng-concepts(7) |