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