doc/man/lttng-track.1.txt

   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)