doc/man/lttng-track.1.txt

   1 lttng-track(1)
   2 ==============
   3 :revdate: 14 March 2017
   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']... | option:--all option:--pid)
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The `lttng track` commands adds one or more entries to a
  21 resource tracker.
  22
  23 A resource tracker is a _whitelist_ of resources. Tracked resources are
  24 allowed to emit events, provided those events are targeted by enabled
  25 event rules (see man:lttng-enable-event(1)).
  26
  27 Tracker entries can be removed from the whitelist with
  28 man:lttng-untrack(1).
  29
  30 As of this version, the only available tracker is the *PID tracker*. The
  31 process ID (PID) tracker follows one or more process IDs; only the
  32 processes with a tracked PID are allowed to emit events. By default, all
  33 possible PIDs on the system are tracked: any process may emit enabled
  34 events (equivalent of `lttng track --pid --all` for all domains).
  35
  36 With the PID tracker, it is possible, for example, to record all system
  37 calls called by a given process:
  38
  39 [role="term"]
  40 ----
  41 # lttng enable-event --kernel --all --syscall
  42 # lttng track --kernel --pid=2345
  43 # lttng start
  44 ----
  45
  46 If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
  47 the default state of all domains when creating a tracing session), then
  48 using the track command with one or more specific PIDs has the effect of
  49 first removing all the PIDs from the whitelist, then adding the
  50 specified PIDs.
  51
  52
  53 Example
  54 ~~~~~~~
  55 Assume the maximum system PID is 7 for this example.
  56
  57 Initial whitelist:
  58
  59 -------------------------------
  60 [0] [1] [2] [3] [4] [5] [6] [7]
  61 -------------------------------
  62
  63 Command:
  64
  65 [role="term"]
  66 ----
  67 $ lttng track --userspace --pid=3,6,7
  68 ----
  69
  70 Whitelist:
  71
  72 -------------------------------
  73 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
  74 -------------------------------
  75
  76 Command:
  77
  78 [role="term"]
  79 ----
  80 $ lttng untrack --userspace --pid=7
  81 ----
  82
  83 Whitelist:
  84
  85 -------------------------------
  86 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
  87 -------------------------------
  88
  89 Command:
  90
  91 [role="term"]
  92 ----
  93 $ lttng track --userspace --pid=1,5
  94 ----
  95
  96 Whitelist:
  97
  98 -------------------------------
  99 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
 100 -------------------------------
 101
 102 It should be noted that the PID tracker tracks the numeric process IDs.
 103 Should a process with a given ID exit and another process be given this
 104 ID, then the latter would also be allowed to emit events.
 105
 106 See the man:lttng-untrack(1) for more details about removing
 107 entries.
 108
 109
 110 include::common-cmd-options-head.txt[]
 111
 112
 113 Domain
 114 ~~~~~~
 115 One of:
 116
 117 option:-k, option:--kernel::
 118     Track resources in the Linux kernel domain.
 119
 120 option:-u, option:--userspace::
 121     Track resources in the user space domain.
 122
 123
 124 Target
 125 ~~~~~~
 126 option:-s 'SESSION', option:--session='SESSION'::
 127     Track resources in the tracing session named 'SESSION' instead of
 128     the current tracing session.
 129
 130
 131 Tracking
 132 ~~~~~~~~
 133 option:-a, option:--all::
 134     Used in conjunction with an empty option:--pid option: track _all_
 135     process IDs (add all entries to the whitelist).
 136
 137 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
 138     Track process IDs 'PID' (add them to the current whitelist).
 139 +
 140 The 'PID' argument must be omitted when also using the option:--all
 141 option.
 142
 143
 144 include::common-cmd-help-options.txt[]
 145
 146
 147 include::common-cmd-footer.txt[]
 148
 149
 150 SEE ALSO
 151 --------
 152 man:lttng-untrack(1),
 153 man:lttng(1)