doc/man/lttng-track.1.txt

   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-untrack(1),
 301 man:lttng-concepts(7)