| 1 | lttng-track(1) |
| 2 | ============== |
| 3 | :revdate: 1 May 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 tracing session named 'SESSION'. |
| 45 | |
| 46 | Without the option:--session option:: |
| 47 | The current tracing session (see man:lttng-concepts(7) to learn more |
| 48 | about the current tracing session). |
| 49 | |
| 50 | See man:lttng-concepts(7) to learn more about tracing 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 tracing |
| 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 tracing session and domain |
| 87 | of{nbsp}__ER__. |
| 88 | |
| 89 | By default, on tracing 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 tracing 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 | Remove values from an inclusion set with the man:lttng-untrack(1) |
| 115 | command. |
| 116 | |
| 117 | |
| 118 | Inclusion set example |
| 119 | ~~~~~~~~~~~~~~~~~~~~~ |
| 120 | This example operates on the Linux kernel process ID (PID) inclusion set |
| 121 | of the current tracing session to show how an inclusion set works. |
| 122 | |
| 123 | Assume the maximum system PID is 7 for this example. |
| 124 | |
| 125 | . Initial inclusion set: |
| 126 | + |
| 127 | ------------------------------- |
| 128 | [0] [1] [2] [3] [4] [5] [6] [7] |
| 129 | ------------------------------- |
| 130 | |
| 131 | . Command: |
| 132 | + |
| 133 | [role="term"] |
| 134 | ---- |
| 135 | $ lttng track --kernel --pid=3,6,7 |
| 136 | ---- |
| 137 | + |
| 138 | Inclusion set is now: |
| 139 | + |
| 140 | ------------------------------- |
| 141 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] |
| 142 | ------------------------------- |
| 143 | |
| 144 | . Command: |
| 145 | + |
| 146 | [role="term"] |
| 147 | ---- |
| 148 | $ lttng untrack --kernel --pid=7 |
| 149 | ---- |
| 150 | + |
| 151 | Inclusion set is now: |
| 152 | + |
| 153 | ------------------------------- |
| 154 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] |
| 155 | ------------------------------- |
| 156 | |
| 157 | . Command: |
| 158 | + |
| 159 | [role="term"] |
| 160 | ---- |
| 161 | $ lttng track --kernel --pid=1,5 |
| 162 | ---- |
| 163 | + |
| 164 | Inclusion set is now: |
| 165 | + |
| 166 | ------------------------------- |
| 167 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] |
| 168 | ------------------------------- |
| 169 | |
| 170 | Remove values from an inclusion set with the man:lttng-untrack(1) |
| 171 | command. |
| 172 | |
| 173 | |
| 174 | include::common-cmd-options-head.txt[] |
| 175 | |
| 176 | |
| 177 | Tracing domain |
| 178 | ~~~~~~~~~~~~~~ |
| 179 | One of: |
| 180 | |
| 181 | option:-k, option:--kernel:: |
| 182 | Add values to one or more Linux kernel inclusion sets. |
| 183 | |
| 184 | option:-u, option:--userspace:: |
| 185 | Add values to one or more user space inclusion sets. |
| 186 | |
| 187 | Recording target |
| 188 | ~~~~~~~~~~~~~~~~ |
| 189 | option:-s 'SESSION', option:--session='SESSION':: |
| 190 | Add values to one or more inclusion sets of the tracing session |
| 191 | named 'SESSION' instead of the current tracing session. |
| 192 | |
| 193 | |
| 194 | Inclusion set selection |
| 195 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 196 | option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: |
| 197 | For each 'PID' argument, add 'PID' to the process ID inclusion set |
| 198 | of the selected tracing session and domain. |
| 199 | + |
| 200 | 'PID' is the process ID attribute of a process as seen from the root |
| 201 | PID namespace (see man:pid_namespaces(7)). |
| 202 | + |
| 203 | Only available with option:--kernel option. |
| 204 | |
| 205 | option:--vpid[='VPID'[,'VPID']...]:: |
| 206 | For each 'VPID' argument, add 'VPID' to the virtual process ID |
| 207 | inclusion set of the selected tracing session and domain. |
| 208 | + |
| 209 | 'VPID' is the virtual process ID attribute of a process as seen from |
| 210 | the PID namespace of the process (see man:pid_namespaces(7)). |
| 211 | |
| 212 | option:--uid[='USER'[,'USER']...]:: |
| 213 | For each 'USER' argument, add 'USER' to the user ID inclusion set of |
| 214 | the selected tracing session and domain. |
| 215 | + |
| 216 | 'USER' is either: |
| 217 | + |
| 218 | -- |
| 219 | * The real user ID (see man:getuid(3)) of a process as seen |
| 220 | from the root user namespace (see man:user_namespaces(7)). |
| 221 | |
| 222 | * A user name. |
| 223 | + |
| 224 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 225 | the user name resolution on addition to the user ID inclusion set. |
| 226 | -- |
| 227 | + |
| 228 | Only available with option:--kernel option. |
| 229 | |
| 230 | option:--vuid[='VUSER'[,'VUSER']...]:: |
| 231 | For each 'VUSER' argument, add 'VUSER' to the virtual user ID |
| 232 | inclusion set of the selected tracing session and domain. |
| 233 | + |
| 234 | 'VUSER' is either: |
| 235 | + |
| 236 | -- |
| 237 | * The real user ID (see man:getuid(3)) of a process as seen |
| 238 | from the user namespace (see man:user_namespaces(7)). |
| 239 | |
| 240 | * A user name. |
| 241 | + |
| 242 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 243 | the user name resolution on addition to the virtual user ID inclusion |
| 244 | set. |
| 245 | -- |
| 246 | |
| 247 | option:--gid[='GROUP'[,'GROUP']...]:: |
| 248 | For each 'GROUP' argument, add 'GROUP' to the group ID |
| 249 | inclusion set of the selected tracing session and domain. |
| 250 | + |
| 251 | 'GROUP' is either: |
| 252 | + |
| 253 | -- |
| 254 | * The real group ID (see man:getgid(3)) of a process as seen from the |
| 255 | root user namespace (see man:user_namespaces(7)). |
| 256 | |
| 257 | * A group name. |
| 258 | + |
| 259 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 260 | the group name resolution on addition to the group ID inclusion set. |
| 261 | -- |
| 262 | + |
| 263 | Only available with option:--kernel option. |
| 264 | |
| 265 | option:--vgid[='VGROUP'[,'VGROUP']...]:: |
| 266 | For each 'VGROUP' argument, add 'VGROUP' to the virtual group ID |
| 267 | inclusion set of the selected tracing session and domain. |
| 268 | + |
| 269 | 'VGROUP' is either: |
| 270 | + |
| 271 | -- |
| 272 | * The real group ID (see man:getgid(3)) of a process as seen |
| 273 | from the user namespace (see man:user_namespaces(7)). |
| 274 | |
| 275 | * A group name. |
| 276 | + |
| 277 | The connected LTTng session daemon (see man:lttng-sessiond(8)) performs |
| 278 | the group name resolution on addition to the virtual group ID inclusion |
| 279 | set. |
| 280 | -- |
| 281 | |
| 282 | |
| 283 | Inclusion set operation |
| 284 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 285 | option:-a, option:--all:: |
| 286 | With one or more empty option:--pid, option:--vpid, option:--uid, |
| 287 | option:--vuid, option:--gid, and option:--vgid options: add *all* |
| 288 | the possible values to the selected inclusion sets. |
| 289 | |
| 290 | |
| 291 | include::common-cmd-help-options.txt[] |
| 292 | |
| 293 | |
| 294 | include::common-cmd-footer.txt[] |
| 295 | |
| 296 | |
| 297 | SEE ALSO |
| 298 | -------- |
| 299 | man:lttng(1), |
| 300 | man:lttng-concepts(7), |
| 301 | man:lttng-untrack(1) |