| 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) |