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