doc/man/lttng-track.1.txt

   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)