doc/man/Makefile.am: fix top comment
[lttng-tools.git] / doc / man / lttng-track.1.txt
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]
13 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *track* (option:--kernel | option:--userspace)
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
24 event rules (see linklttng:lttng-enable-event(1)).
25
26 Tracker entries can be removed from the whitelist with
27 linklttng:lttng-untrack(1).
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
38 [role="term"]
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
64 [role="term"]
65 -----------------------------------
66 lttng track --userspace --pid=3,6,7
67 -----------------------------------
68
69 Whitelist:
70
71 -------------------------------
72 [ ] [ ] [ ] [3] [ ] [ ] [6] [7]
73 -------------------------------
74
75 Command:
76
77 [role="term"]
78 ---------------------------------
79 lttng untrack --userspace --pid=7
80 ---------------------------------
81
82 Whitelist:
83
84 -------------------------------
85 [ ] [ ] [ ] [3] [ ] [ ] [6] [ ]
86 -------------------------------
87
88 Command:
89
90 [role="term"]
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
105 See the linklttng:lttng-untrack(1) for more details about removing
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 ~~~~~~
125 option:-s, option:--session='SESSION'::
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
136 option:-p, option:--pid[='PID'[,'PID']...]::
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 --------
151 linklttng:lttng-untrack(1),
152 linklttng:lttng(1)
This page took 0.033579 seconds and 5 git commands to generate.