doc/man/Makefile.am: add failing dist-hook on --disable-man-pages
[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
24event rules (see linklttng:lttng-enable-event(1)).
25
26Tracker entries can be removed from the whitelist with
27linklttng:lttng-untrack(1).
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
105See the linklttng:lttng-untrack(1) for more details about removing
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~~~~~~
125option:-s, option:--session='SESSION'::
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
136option:-p, option:--pid[='PID'[,'PID']...]::
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--------
151linklttng:lttng-untrack(1),
152linklttng:lttng(1)
This page took 0.040424 seconds and 4 git commands to generate.