doc/man/lttng-track.1.txt

   1 lttng-track(1)
   2 ==============
   3 :revdate: 04 November 2019
   4
   5
   6 NAME
   7 ----
   8 lttng-track - Add one or more entries to an LTTng resource tracker
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
  15       [option:--session='SESSION'] (option:--pid='PID'[,'PID']... |
  16       option:--uid='UID'[,'UID'][,'USERNAME']... |
  17       option:--gid='GID'[,'GID'][,'GROUPNAME']... |
  18       option:--vpid='VPID'[,'VPID']... |
  19       option:--vuid='VUID'[,'VUID'][,'USERNAME']... |
  20       option:--vgid='VGID'[,'VGID'][,'GROUPNAME']... |
  21       option:--all (option:--pid | option:--uid | option:--gid | option:--vpid | option:--vuid | option:--vgid))
  22
  23
  24 DESCRIPTION
  25 -----------
  26 The `lttng track` commands adds one or more entries to a
  27 resource tracker.
  28
  29 A resource tracker is a _whitelist_ of resources. Tracked resources are
  30 allowed to emit events, provided those events are targeted by enabled
  31 event rules (see man:lttng-enable-event(1)).
  32
  33 Tracker entries can be removed from the whitelist with
  34 man:lttng-untrack(1).
  35
  36 The following tracker are available: PID, UID, GID, VPID, VUID, VGID.
  37
  38 A tracker follows one or more IDs; only the processes with a tracked ID are
  39 allowed to emit events. By default, all possible IDs on the system are tracked:
  40 any process may emit enabled events (equivalent of `lttng track --pid --uid
  41 --gid --vpid --vuid --vgid --all` for all domains).
  42
  43 With the PID tracker, it is possible, for example, to record all system
  44 calls called by a given process:
  45
  46 [role="term"]
  47 ----
  48 # lttng enable-event --kernel --all --syscall
  49 # lttng track --kernel --pid=2345
  50 # lttng start
  51 ----
  52
  53 If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
  54 the default state of all domains when creating a tracing session), then
  55 using the track command with one or more specific PIDs has the effect of
  56 first removing all the PIDs from the whitelist, then adding the
  57 specified PIDs.
  58
  59
  60 Example
  61 ~~~~~~~
  62 Assume the maximum system VPID is 7 for this example.
  63
  64 Initial whitelist:
  65
  66 -------------------------------
  67 [0] [1] [2] [3] [4] [5] [6] [7]
  68 -------------------------------
  69
  70 Command:
  71
  72 [role="term"]
  73 ----
  74 $ lttng track --userspace --vpid=3,6,7
  75 ----
  76
  77 Whitelist:
  78
  79 -------------------------------
  80 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
  81 -------------------------------
  82
  83 Command:
  84
  85 [role="term"]
  86 ----
  87 $ lttng untrack --userspace --vpid=7
  88 ----
  89
  90 Whitelist:
  91
  92 -------------------------------
  93 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
  94 -------------------------------
  95
  96 Command:
  97
  98 [role="term"]
  99 ----
 100 $ lttng track --userspace --vpid=1,5
 101 ----
 102
 103 Whitelist:
 104
 105 -------------------------------
 106 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
 107 -------------------------------
 108
 109 It should be noted that the VPID tracker tracks the numeric namespaced process
 110 IDs. Should a process with a given ID exit and another process be given this ID,
 111 then the latter would also be allowed to emit events.
 112
 113 See the man:lttng-untrack(1) for more details about removing
 114 entries.
 115
 116
 117 include::common-cmd-options-head.txt[]
 118
 119
 120 Domain
 121 ~~~~~~
 122 One of:
 123
 124 option:-k, option:--kernel::
 125     Track resources in the Linux kernel domain.
 126
 127 option:-u, option:--userspace::
 128     Track resources in the user space domain.
 129
 130
 131 Target
 132 ~~~~~~
 133 option:-s 'SESSION', option:--session='SESSION'::
 134     Track resources in the tracing session named 'SESSION' instead of
 135     the current tracing session.
 136
 137
 138 Tracking
 139 ~~~~~~~~
 140 option:-a, option:--all::
 141     Used in conjunction with an empty tracker option, e.g: options:--pid track _all_
 142     process IDs (add all entries to the whitelist).
 143
 144 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
 145     Track process IDs 'PID' (add them to the current whitelist).
 146     PID is the non-namespaced value for the process.
 147 +
 148 The 'PID' argument must be omitted when also using the option:--all
 149 option.
 150
 151 option:-p ['UID'[,'UID']...], option:--uid[='UID'[,'UID'][,'USERNAME']...]::
 152     Track process IDs 'UID' (add them to the current whitelist).
 153     User name can also be used, name resolution is performed by
 154     lttng-sessiond.
 155     UID is the non-namespaced user id value for the process.
 156 +
 157 The 'UID' argument must be omitted when also using the option:--all
 158 option.
 159
 160 option:-p ['GID'[,'GID']...], option:--gid[='GID'[,'GID'][,'GROUPNAME']...]::
 161     Track process IDs 'GID' (add them to the current whitelist).
 162     Group name can also be used, name resolution is performed by
 163     lttng-sessiond.
 164     GID is the non-namespaced group id value for the process.
 165 +
 166 The 'GID' argument must be omitted when also using the option:--all
 167 option.
 168
 169 option:-p ['VPID'[,'VPID']...], option:--vpid[='VPID'[,'VPID']...]::
 170     Track process IDs 'VPID' (add them to the current whitelist).
 171     VPID is the namespaced PID of the process for its current context.
 172 +
 173 The 'VPID' argument must be omitted when also using the option:--all
 174 option.
 175
 176 option:-p ['VUID'[,'VUID']...], option:--vuid[='VUID'[,'VUID'][,'USERNAME']...]::
 177     Track process IDs 'VUID' (add them to the current whitelist).
 178     User name can also be used, name resolution is performed by
 179     lttng-sessiond.
 180     VUID is the namespaced UID of the process for its current context.
 181 +
 182 The 'VUID' argument must be omitted when also using the option:--all
 183 option.
 184
 185 option:-p ['VGID'[,'VGID']...], option:--vgid[='VGID'[,'VGID'][,'GROUPNAME']...]::
 186     Track process IDs 'VGID' (add them to the current whitelist).
 187     Group name can also be used, name resolution is performed by
 188     lttng-sessiond.
 189     VGID is the namespaced GID of the process for its current context.
 190 +
 191 The 'VGID' argument must be omitted when also using the option:--all
 192 option.
 193
 194
 195 include::common-cmd-help-options.txt[]
 196
 197
 198 include::common-cmd-footer.txt[]
 199
 200
 201 SEE ALSO
 202 --------
 203 man:lttng-untrack(1),
 204 man:lttng(1)