Commit | Line | Data |
---|---|---|
65226554 PP |
1 | lttng-track(1) |
2 | ============== | |
3 | ||
4 | ||
5 | NAME | |
6 | ---- | |
7 | lttng-track - Add one or more entries to an LTTng resource tracker | |
8 | ||
9 | ||
10 | SYNOPSIS | |
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 | ||
17 | DESCRIPTION | |
18 | ----------- | |
19 | The `lttng track` commands adds one or more entries to a | |
20 | resource tracker. | |
21 | ||
22 | A resource tracker is a _whitelist_ of resources. Tracked resources are | |
23 | allowed to emit events, provided those events are targeted by enabled | |
7c1a4458 | 24 | event rules (see man:lttng-enable-event(1)). |
65226554 PP |
25 | |
26 | Tracker entries can be removed from the whitelist with | |
7c1a4458 | 27 | man:lttng-untrack(1). |
65226554 PP |
28 | |
29 | As of this version, the only available tracker is the *PID tracker*. The | |
30 | process ID (PID) tracker follows one or more process IDs; only the | |
31 | processes with a tracked PID are allowed to emit events. By default, all | |
32 | possible PIDs on the system are tracked: any process may emit enabled | |
33 | events (equivalent of `lttng track --pid --all` for all domains). | |
34 | ||
35 | With the PID tracker, it is possible, for example, to record all system | |
36 | calls called by a given process: | |
37 | ||
d4f093aa | 38 | [role="term"] |
65226554 PP |
39 | ------------------------------------------- |
40 | lttng enable-event --kernel --all --syscall | |
41 | lttng track --kernel --pid=2345 | |
42 | lttng start | |
43 | ------------------------------------------- | |
44 | ||
45 | If all the PIDs are tracked (i.e. `lttng track --pid --all`, which is | |
46 | the default state of all domains when creating a tracing session), then | |
47 | using the track command with one or more specific PIDs has the effect of | |
48 | first removing all the PIDs from the whitelist, then adding the | |
49 | specified PIDs. | |
50 | ||
51 | ||
52 | Example | |
53 | ~~~~~~~ | |
54 | Assume the maximum system PID is 7 for this example. | |
55 | ||
56 | Initial whitelist: | |
57 | ||
58 | ------------------------------- | |
59 | [0] [1] [2] [3] [4] [5] [6] [7] | |
60 | ------------------------------- | |
61 | ||
62 | Command: | |
63 | ||
d4f093aa | 64 | [role="term"] |
65226554 PP |
65 | ----------------------------------- |
66 | lttng track --userspace --pid=3,6,7 | |
67 | ----------------------------------- | |
68 | ||
69 | Whitelist: | |
70 | ||
71 | ------------------------------- | |
72 | [ ] [ ] [ ] [3] [ ] [ ] [6] [7] | |
73 | ------------------------------- | |
74 | ||
75 | Command: | |
76 | ||
d4f093aa | 77 | [role="term"] |
65226554 PP |
78 | --------------------------------- |
79 | lttng untrack --userspace --pid=7 | |
80 | --------------------------------- | |
81 | ||
82 | Whitelist: | |
83 | ||
84 | ------------------------------- | |
85 | [ ] [ ] [ ] [3] [ ] [ ] [6] [ ] | |
86 | ------------------------------- | |
87 | ||
88 | Command: | |
89 | ||
d4f093aa | 90 | [role="term"] |
65226554 PP |
91 | --------------------------------- |
92 | lttng track --userspace --pid=1,5 | |
93 | --------------------------------- | |
94 | ||
95 | Whitelist: | |
96 | ||
97 | ------------------------------- | |
98 | [ ] [1] [ ] [3] [ ] [5] [6] [ ] | |
99 | ------------------------------- | |
100 | ||
101 | It should be noted that the PID tracker tracks the numeric process IDs. | |
102 | Should a process with a given ID exit and another process be given this | |
103 | ID, then the latter would also be allowed to emit events. | |
104 | ||
7c1a4458 | 105 | See the man:lttng-untrack(1) for more details about removing |
65226554 PP |
106 | entries. |
107 | ||
108 | ||
109 | include::common-cmd-options-head.txt[] | |
110 | ||
111 | ||
112 | Domain | |
113 | ~~~~~~ | |
114 | One of: | |
115 | ||
116 | option:-k, option:--kernel:: | |
117 | Track resources in the Linux kernel domain. | |
118 | ||
119 | option:-u, option:--userspace:: | |
120 | Track resources in the user space domain. | |
121 | ||
122 | ||
123 | Target | |
124 | ~~~~~~ | |
59b19c3c | 125 | option:-s 'SESSION', option:--session='SESSION':: |
65226554 PP |
126 | Track resources in the tracing session named 'SESSION' instead of |
127 | the current tracing session. | |
128 | ||
129 | ||
130 | Tracking | |
131 | ~~~~~~~~ | |
132 | option:-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 | ||
59b19c3c | 136 | option:-p ['PID'[,'PID']...], option:--pid[='PID'[,'PID']...]:: |
65226554 PP |
137 | Track process IDs 'PID' (add them to the current whitelist). |
138 | + | |
139 | The 'PID' argument must be omitted when also using the option:--all | |
140 | option. | |
141 | ||
142 | ||
143 | include::common-cmd-help-options.txt[] | |
144 | ||
145 | ||
146 | include::common-cmd-footer.txt[] | |
147 | ||
148 | ||
149 | SEE ALSO | |
150 | -------- | |
7c1a4458 PP |
151 | man:lttng-untrack(1), |
152 | man:lttng(1) |