Commit | Line | Data |
---|---|---|
65226554 PP |
1 | lttng-track(1) |
2 | ============== | |
9bd01b5e | 3 | :revdate: 04 November 2019 |
65226554 PP |
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] | |
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 | ||
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 | |
7c1a4458 | 31 | event rules (see man:lttng-enable-event(1)). |
65226554 PP |
32 | |
33 | Tracker entries can be removed from the whitelist with | |
7c1a4458 | 34 | man:lttng-untrack(1). |
65226554 | 35 | |
9bd01b5e JR |
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). | |
65226554 PP |
42 | |
43 | With the PID tracker, it is possible, for example, to record all system | |
44 | calls 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 | |
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 | ~~~~~~~ | |
9bd01b5e | 62 | Assume the maximum system VPID is 7 for this example. |
65226554 PP |
63 | |
64 | Initial whitelist: | |
65 | ||
66 | ------------------------------- | |
67 | [0] [1] [2] [3] [4] [5] [6] [7] | |
68 | ------------------------------- | |
69 | ||
70 | Command: | |
71 | ||
d4f093aa | 72 | [role="term"] |
03c5529d | 73 | ---- |
9bd01b5e | 74 | $ lttng track --userspace --vpid=3,6,7 |
03c5529d | 75 | ---- |
65226554 PP |
76 | |
77 | Whitelist: | |
78 | ||
79 | ------------------------------- | |
80 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
81 | ------------------------------- | |
82 | ||
83 | Command: | |
84 | ||
d4f093aa | 85 | [role="term"] |
03c5529d | 86 | ---- |
9bd01b5e | 87 | $ lttng untrack --userspace --vpid=7 |
03c5529d | 88 | ---- |
65226554 PP |
89 | |
90 | Whitelist: | |
91 | ||
92 | ------------------------------- | |
93 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
94 | ------------------------------- | |
95 | ||
96 | Command: | |
97 | ||
d4f093aa | 98 | [role="term"] |
03c5529d | 99 | ---- |
9bd01b5e | 100 | $ lttng track --userspace --vpid=1,5 |
03c5529d | 101 | ---- |
65226554 PP |
102 | |
103 | Whitelist: | |
104 | ||
105 | ------------------------------- | |
106 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
107 | ------------------------------- | |
108 | ||
9bd01b5e JR |
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. | |
65226554 | 112 | |
7c1a4458 | 113 | See the man:lttng-untrack(1) for more details about removing |
65226554 PP |
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 | ~~~~~~ | |
59b19c3c | 133 | option:-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 | ||
138 | Tracking | |
139 | ~~~~~~~~ | |
140 | option:-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 | 144 | option:-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 | + |
148 | The 'PID' argument must be omitted when also using the option:--all | |
149 | option. | |
150 | ||
9bd01b5e JR |
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 | ||
65226554 PP |
194 | |
195 | include::common-cmd-help-options.txt[] | |
196 | ||
197 | ||
198 | include::common-cmd-footer.txt[] | |
199 | ||
200 | ||
201 | SEE ALSO | |
202 | -------- | |
7c1a4458 PP |
203 | man:lttng-untrack(1), |
204 | man:lttng(1) |