| 1 | lttng-track(1) |
| 2 | ============== |
| 3 | |
| 4 | |
| 5 | NAME |
| 6 | ---- |
| 7 | lttng-track - Add one or more property values to an LTTng process tracker |
| 8 | |
| 9 | |
| 10 | SYNOPSIS |
| 11 | -------- |
| 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 | |
| 25 | [verse] |
| 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] |
| 30 | |
| 31 | |
| 32 | DESCRIPTION |
| 33 | ----------- |
| 34 | The `lttng track` commands adds one or more property values to an LTTng |
| 35 | process tracker. |
| 36 | |
| 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)). |
| 42 | |
| 43 | You can remove process property values from the whitelist with |
| 44 | man:lttng-untrack(1). |
| 45 | |
| 46 | The available process properties are: |
| 47 | |
| 48 | option:--pid:: |
| 49 | Process ID as seen by the Linux kernel (root namespace). |
| 50 | |
| 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. |
| 74 | |
| 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. |
| 79 | |
| 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. |
| 83 | |
| 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 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 93 | Assume the maximum system PID is 7 for this example. |
| 94 | |
| 95 | Initial PID whitelist: |
| 96 | |
| 97 | ------------------------------- |
| 98 | [0] [1] [2] [3] [4] [5] [6] [7] |
| 99 | ------------------------------- |
| 100 | |
| 101 | Command: |
| 102 | |
| 103 | [role="term"] |
| 104 | ---- |
| 105 | $ lttng track --kernel --pid=3,6,7 |
| 106 | ---- |
| 107 | |
| 108 | Whitelist: |
| 109 | |
| 110 | ------------------------------- |
| 111 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] |
| 112 | ------------------------------- |
| 113 | |
| 114 | Command: |
| 115 | |
| 116 | [role="term"] |
| 117 | ---- |
| 118 | $ lttng untrack --kernel --pid=7 |
| 119 | ---- |
| 120 | |
| 121 | Whitelist: |
| 122 | |
| 123 | ------------------------------- |
| 124 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] |
| 125 | ------------------------------- |
| 126 | |
| 127 | Command: |
| 128 | |
| 129 | [role="term"] |
| 130 | ---- |
| 131 | $ lttng track --kernel --pid=1,5 |
| 132 | ---- |
| 133 | |
| 134 | Whitelist: |
| 135 | |
| 136 | ------------------------------- |
| 137 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] |
| 138 | ------------------------------- |
| 139 | |
| 140 | See the man:lttng-untrack(1) for more details about removing property |
| 141 | values from the whitelist. |
| 142 | |
| 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 | ---- |
| 177 | |
| 178 | |
| 179 | include::common-cmd-options-head.txt[] |
| 180 | |
| 181 | |
| 182 | Domain |
| 183 | ~~~~~~ |
| 184 | One of: |
| 185 | |
| 186 | option:-k, option:--kernel:: |
| 187 | Track processes for Linux kernel channels. |
| 188 | |
| 189 | option:-u, option:--userspace:: |
| 190 | Track processes for user space channels. |
| 191 | |
| 192 | |
| 193 | Target |
| 194 | ~~~~~~ |
| 195 | option:-s 'SESSION', option:--session='SESSION':: |
| 196 | Track processes in the tracing session named 'SESSION' instead of |
| 197 | the current tracing session. |
| 198 | |
| 199 | |
| 200 | Process property |
| 201 | ~~~~~~~~~~~~~~~~ |
| 202 | option:-a, option:--all:: |
| 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. |
| 222 | |
| 223 | option:--vpid[='PID'[,'PID']...]:: |
| 224 | Add process ID 'VPID', as seen by the traced process, to the |
| 225 | tracker's whitelist. |
| 226 | |
| 227 | option:--vuid[='USER'[,'USER']...]:: |
| 228 | Add user ID or name 'USER', as seen by the traced process, to the |
| 229 | tracker's whitelist. |
| 230 | |
| 231 | include::common-cmd-help-options.txt[] |
| 232 | |
| 233 | |
| 234 | include::common-cmd-footer.txt[] |
| 235 | |
| 236 | |
| 237 | SEE ALSO |
| 238 | -------- |
| 239 | man:lttng-untrack(1), |
| 240 | man:lttng(1) |