doc/man/lttng-track.1.txt

   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)