Fix: MI: bump MI schema version to 4.0 in mi-lttng.c
[lttng-tools.git] / doc / man / lttng-track.1.txt
CommitLineData
65226554
PP
1lttng-track(1)
2==============
9bd01b5e 3:revdate: 04 November 2019
65226554
PP
4
5
6NAME
7----
8lttng-track - Add one or more entries to an LTTng resource tracker
9
10
11SYNOPSIS
12--------
13[verse]
ce19b9ed 14*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
9bd01b5e
JR
15 [option:--session='SESSION'] (option:--pid='PID'[,'PID']... |
16 option:--uid='UID'[,'UID'][,'USERNAME']... |
17 option:--gid='GID'[,'GID'][,'GROUPNAME']... |
18 option:--vpid='VPID'[,'VPID']... |
19 option:--vuid='VUID'[,'VUID'][,'USERNAME']... |
20 option:--vgid='VGID'[,'VGID'][,'GROUPNAME']... |
21 option:--all (option:--pid | option:--uid | option:--gid | option:--vpid | option:--vuid | option:--vgid))
65226554
PP
22
23
24DESCRIPTION
25-----------
26The `lttng track` commands adds one or more entries to a
27resource tracker.
28
29A resource tracker is a _whitelist_ of resources. Tracked resources are
30allowed to emit events, provided those events are targeted by enabled
7c1a4458 31event rules (see man:lttng-enable-event(1)).
65226554
PP
32
33Tracker entries can be removed from the whitelist with
7c1a4458 34man:lttng-untrack(1).
65226554 35
9bd01b5e
JR
36The following tracker are available: PID, UID, GID, VPID, VUID, VGID.
37
38A tracker follows one or more IDs; only the processes with a tracked ID are
39allowed to emit events. By default, all possible IDs on the system are tracked:
40any process may emit enabled events (equivalent of `lttng track --pid --uid
41--gid --vpid --vuid --vgid --all` for all domains).
65226554
PP
42
43With the PID tracker, it is possible, for example, to record all system
44calls called by a given process:
45
d4f093aa 46[role="term"]
03c5529d
PP
47----
48# lttng enable-event --kernel --all --syscall
49# lttng track --kernel --pid=2345
50# lttng start
51----
65226554
PP
52
53If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is
54the default state of all domains when creating a tracing session), then
55using the track command with one or more specific PIDs has the effect of
56first removing all the PIDs from the whitelist, then adding the
57specified PIDs.
58
59
60Example
61~~~~~~~
9bd01b5e 62Assume the maximum system VPID is 7 for this example.
65226554
PP
63
64Initial whitelist:
65
66-------------------------------
67[0] [1] [2] [3] [4] [5] [6] [7]
68-------------------------------
69
70Command:
71
d4f093aa 72[role="term"]
03c5529d 73----
9bd01b5e 74$ lttng track --userspace --vpid=3,6,7
03c5529d 75----
65226554
PP
76
77Whitelist:
78
79-------------------------------
80[ ] [ ] [ ] [3] [ ] [ ] [6] [7]
81-------------------------------
82
83Command:
84
d4f093aa 85[role="term"]
03c5529d 86----
9bd01b5e 87$ lttng untrack --userspace --vpid=7
03c5529d 88----
65226554
PP
89
90Whitelist:
91
92-------------------------------
93[ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
94-------------------------------
95
96Command:
97
d4f093aa 98[role="term"]
03c5529d 99----
9bd01b5e 100$ lttng track --userspace --vpid=1,5
03c5529d 101----
65226554
PP
102
103Whitelist:
104
105-------------------------------
106[ ] [1] [ ] [3] [ ] [5] [6] [ ]
107-------------------------------
108
9bd01b5e
JR
109It should be noted that the VPID tracker tracks the numeric namespaced process
110IDs. Should a process with a given ID exit and another process be given this ID,
111then the latter would also be allowed to emit events.
65226554 112
7c1a4458 113See the man:lttng-untrack(1) for more details about removing
65226554
PP
114entries.
115
116
117include::common-cmd-options-head.txt[]
118
119
120Domain
121~~~~~~
122One of:
123
124option:-k, option:--kernel::
125 Track resources in the Linux kernel domain.
126
127option:-u, option:--userspace::
128 Track resources in the user space domain.
129
130
131Target
132~~~~~~
59b19c3c 133option:-s 'SESSION', option:--session='SESSION'::
65226554
PP
134 Track resources in the tracing session named 'SESSION' instead of
135 the current tracing session.
136
137
138Tracking
139~~~~~~~~
140option:-a, option:--all::
9bd01b5e 141 Used in conjunction with an empty tracker option, e.g: options:--pid track _all_
65226554
PP
142 process IDs (add all entries to the whitelist).
143
59b19c3c 144option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]::
65226554 145 Track process IDs 'PID' (add them to the current whitelist).
9bd01b5e 146 PID is the non-namespaced value for the process.
65226554
PP
147+
148The 'PID' argument must be omitted when also using the option:--all
149option.
150
9bd01b5e
JR
151option:-p ['UID'[,'UID']...], option:--uid[='UID'[,'UID'][,'USERNAME']...]::
152 Track process IDs 'UID' (add them to the current whitelist).
153 User name can also be used, name resolution is performed by
154 lttng-sessiond.
155 UID is the non-namespaced user id value for the process.
156+
157The 'UID' argument must be omitted when also using the option:--all
158option.
159
160option:-p ['GID'[,'GID']...], option:--gid[='GID'[,'GID'][,'GROUPNAME']...]::
161 Track process IDs 'GID' (add them to the current whitelist).
162 Group name can also be used, name resolution is performed by
163 lttng-sessiond.
164 GID is the non-namespaced group id value for the process.
165+
166The 'GID' argument must be omitted when also using the option:--all
167option.
168
169option:-p ['VPID'[,'VPID']...], option:--vpid[='VPID'[,'VPID']...]::
170 Track process IDs 'VPID' (add them to the current whitelist).
171 VPID is the namespaced PID of the process for its current context.
172+
173The 'VPID' argument must be omitted when also using the option:--all
174option.
175
176option:-p ['VUID'[,'VUID']...], option:--vuid[='VUID'[,'VUID'][,'USERNAME']...]::
177 Track process IDs 'VUID' (add them to the current whitelist).
178 User name can also be used, name resolution is performed by
179 lttng-sessiond.
180 VUID is the namespaced UID of the process for its current context.
181+
182The 'VUID' argument must be omitted when also using the option:--all
183option.
184
185option:-p ['VGID'[,'VGID']...], option:--vgid[='VGID'[,'VGID'][,'GROUPNAME']...]::
186 Track process IDs 'VGID' (add them to the current whitelist).
187 Group name can also be used, name resolution is performed by
188 lttng-sessiond.
189 VGID is the namespaced GID of the process for its current context.
190+
191The 'VGID' argument must be omitted when also using the option:--all
192option.
193
65226554
PP
194
195include::common-cmd-help-options.txt[]
196
197
198include::common-cmd-footer.txt[]
199
200
201SEE ALSO
202--------
7c1a4458
PP
203man:lttng-untrack(1),
204man:lttng(1)
This page took 0.053848 seconds and 4 git commands to generate.