Clean-up shm directory tree after freeing the channel
[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]
13*lttng* ['GENERAL OPTIONS'] *track* (option:--kernel | option:--userspace)
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
38-------------------------------------------
39lttng enable-event --kernel --all --syscall
40lttng track --kernel --pid=2345
41lttng start
42-------------------------------------------
43
44If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
45the default state of all domains when creating a tracing session), then
46using the track command with one or more specific PIDs has the effect of
47first removing all the PIDs from the whitelist, then adding the
48specified PIDs.
49
50
51Example
52~~~~~~~
53Assume the maximum system PID is 7 for this example.
54
55Initial whitelist:
56
57-------------------------------
58[0] [1] [2] [3] [4] [5] [6] [7]
59-------------------------------
60
61Command:
62
63-----------------------------------
64lttng track --userspace --pid=3,6,7
65-----------------------------------
66
67Whitelist:
68
69-------------------------------
70[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
71-------------------------------
72
73Command:
74
75---------------------------------
76lttng untrack --userspace --pid=7
77---------------------------------
78
79Whitelist:
80
81-------------------------------
82[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
83-------------------------------
84
85Command:
86
87---------------------------------
88lttng track --userspace --pid=1,5
89---------------------------------
90
91Whitelist:
92
93-------------------------------
94[ ] [1] [ ] [3] [ ] [5] [6] [ ]
95-------------------------------
96
97It should be noted that the PID tracker tracks the numeric process IDs.
98Should a process with a given ID exit and another process be given this
99ID, then the latter would also be allowed to emit events.
100
101See the linklttng:lttng-untrack(1) for more details about removing
102entries.
103
104
105include::common-cmd-options-head.txt[]
106
107
108Domain
109~~~~~~
110One of:
111
112option:-k, option:--kernel::
113 Track resources in the Linux kernel domain.
114
115option:-u, option:--userspace::
116 Track resources in the user space domain.
117
118
119Target
120~~~~~~
121option:-s, option:--session='SESSION'::
122 Track resources in the tracing session named 'SESSION' instead of
123 the current tracing session.
124
125
126Tracking
127~~~~~~~~
128option:-a, option:--all::
129 Used in conjunction with an empty option:--pid option: track _all_
130 process IDs (add all entries to the whitelist).
131
132option:-p, option:--pid[='PID'[,'PID']...]::
133 Track process IDs 'PID' (add them to the current whitelist).
134+
135The 'PID' argument must be omitted when also using the option:--all
136option.
137
138
139include::common-cmd-help-options.txt[]
140
141
142include::common-cmd-footer.txt[]
143
144
145SEE ALSO
146--------
147linklttng:lttng-untrack(1),
148linklttng:lttng(1)
This page took 0.038317 seconds and 4 git commands to generate.