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