3 :revdate: 14 March 2017
8 lttng-track - Add one or more entries to an LTTng resource tracker
14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
15 [option:--session='SESSION'] (option:--pid='PID'[,'PID']... | option:--all option:--pid)
20 The `lttng track` commands adds one or more entries to a
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)).
27 Tracker entries can be removed from the whitelist with
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).
36 With the PID tracker, it is possible, for example, to record all system
37 calls called by a given process:
41 # lttng enable-event --kernel --all --syscall
42 # lttng track --kernel --pid=2345
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
55 Assume the maximum system PID is 7 for this example.
59 -------------------------------
60 [0] [1] [2] [3] [4] [5] [6] [7]
61 -------------------------------
67 $ lttng track --userspace --pid=3,6,7
72 -------------------------------
73 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
74 -------------------------------
80 $ lttng untrack --userspace --pid=7
85 -------------------------------
86 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
87 -------------------------------
93 $ lttng track --userspace --pid=1,5
98 -------------------------------
99 [ ] [1] [ ] [3] [ ] [5] [6] [ ]
100 -------------------------------
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.
106 See the man:lttng-untrack(1) for more details about removing
110 include::common-cmd-options-head.txt[]
117 option:-k, option:--kernel::
118 Track resources in the Linux kernel domain.
120 option:-u, option:--userspace::
121 Track resources in the user space domain.
126 option:-s 'SESSION', option:--session='SESSION'::
127 Track resources in the tracing session named 'SESSION' instead of
128 the current tracing session.
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).
137 option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
138 Track process IDs 'PID' (add them to the current whitelist).
140 The 'PID' argument must be omitted when also using the option:--all
144 include::common-cmd-help-options.txt[]
147 include::common-cmd-footer.txt[]
152 man:lttng-untrack(1),