doc/man/lttng-track.1.txt

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