Commit | Line | Data |
---|---|---|
b4867b3b PP |
1 | lttng-enable-channel(1) |
2 | ======================= | |
3 | ||
4 | ||
5 | NAME | |
6 | ---- | |
7 | lttng-enable-channel - Create or enable LTTng channels | |
8 | ||
9 | ||
10 | SYNOPSIS | |
11 | -------- | |
12 | Create a Linux kernel channel: | |
13 | ||
14 | [verse] | |
15 | *lttng* ['GENERAL OPTIONS'] *enable-channel* option:--kernel | |
16 | [option:--discard | option:--overwrite] [option:--output=(`mmap` | `splice`)] | |
17 | [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] | |
18 | [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] | |
19 | [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] | |
20 | [option:--session='SESSION'] 'CHANNEL' | |
21 | ||
22 | Create a user space channel: | |
23 | ||
24 | [verse] | |
25 | *lttng* ['GENERAL OPTIONS'] *enable-channel* option:--userspace | |
26 | [option:--discard | option:--overwrite] [option:--buffers-pid] | |
27 | [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] | |
28 | [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] | |
29 | [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] | |
30 | [option:--session='SESSION'] 'CHANNEL' | |
31 | ||
32 | Enable existing channel(s): | |
33 | ||
34 | [verse] | |
35 | *lttng* ['GENERAL OPTIONS'] *enable-channel* (option:--userspace | option:--kernel) | |
36 | [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']... | |
37 | ||
38 | ||
39 | DESCRIPTION | |
40 | ----------- | |
41 | The `lttng enable-channel` command can create a new channel, or enable | |
42 | one or more existing and disabled ones. | |
43 | ||
44 | A channel is the owner of sub-buffers holding recorded events. Event, | |
45 | rules, when created using linklttng:lttng-enable-event(1), are always | |
46 | assigned to a channel. When creating a new channel, many parameters | |
47 | related to those sub-buffers can be fine-tuned. They are described in | |
48 | the subsections below. | |
49 | ||
50 | When 'CHANNEL' does not name an existing channel, a channel named | |
51 | 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL' | |
52 | is enabled. | |
53 | ||
54 | Note that the linklttng:lttng-enable-event(1) command can automatically | |
55 | create default channels when no channel exist. | |
56 | ||
57 | A channel is always contained in a tracing session | |
58 | (see linklttng:lttng-create(1) for creating a tracing session). The | |
59 | session in which a channel is created using `lttng enable-channel` can | |
60 | be specified using the option:--session option. If the option:--session | |
61 | option is omitted, the current tracing session is targeted. | |
62 | ||
63 | Existing enabled channels can be disabled using | |
64 | linklttng:lttng-disable-channel(1). Channels of a given session can be | |
65 | listed using linklttng:lttng-list(1). | |
66 | ||
67 | As of this version of LTTng, it is not possible to: | |
68 | ||
69 | * Reconfigure a channel once it is created. | |
70 | * Re-enable a disabled channel once its tracing session has been active | |
71 | at least once. | |
72 | * Create a channel once its tracing session has been active | |
73 | at least once. | |
74 | * Create a user space channel with a given buffering scheme | |
75 | (option:--buffers-uid or option:--buffers-pid options) and create | |
76 | a second user space channel with a different buffering scheme in the | |
77 | same tracing session. | |
78 | ||
79 | ||
80 | Event loss modes | |
81 | ~~~~~~~~~~~~~~~~ | |
82 | LTTng tracers are non-blocking: when no empty sub-buffer exists, | |
83 | losing events is acceptable when the alternative would be to cause | |
84 | substantial delays in the instrumented application's execution. | |
85 | ||
86 | LTTng privileges performance over integrity, aiming at perturbing the | |
87 | traced system as little as possible in order to make tracing of subtle | |
88 | race conditions and rare interrupt cascades possible. | |
89 | ||
90 | When it comes to losing events because no empty sub-buffer is available, | |
91 | the channel's event loss mode, specified by one of the option:--discard | |
92 | and option:--overwrite options, determines what to do amongst: | |
93 | ||
94 | Discard:: | |
95 | Drop the newest events until a sub-buffer is released. | |
96 | ||
97 | Overwrite:: | |
98 | Clear the sub-buffer containing the oldest recorded events and start | |
99 | recording the newest events there. This mode is sometimes called | |
100 | _flight recorder mode_ because it behaves like a flight recorder: | |
101 | always keep a fixed amount of the latest data. | |
102 | ||
103 | Which mechanism to choose depends on the context: prioritize the newest | |
104 | or the oldest events in the ring buffer? | |
105 | ||
106 | Beware that, in overwrite mode (option:--overwrite option), a whole | |
107 | sub-buffer is abandoned as soon as a new event doesn't find an empty | |
108 | sub-buffer, whereas in discard mode (option:--discard option), only the | |
109 | event that doesn't fit is discarded. | |
110 | ||
111 | Also note that a count of lost events is incremented and saved in the | |
112 | trace itself when an event is lost in discard mode, whereas no | |
113 | information is kept when a sub-buffer gets overwritten before being | |
114 | committed. | |
115 | ||
116 | The probability of losing events, if it is experience in a given | |
117 | context, can be reduced by fine-tuning the sub-buffers count and size | |
118 | (see next subsection). | |
119 | ||
120 | ||
121 | Sub-buffers count and size | |
122 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
123 | The option:--num-subbuf and option:--subbuf-size options respectively | |
124 | set the number of sub-buffers and their individual size when creating | |
125 | a new channel. | |
126 | ||
127 | Note that there is a noticeable tracer's CPU overhead introduced when | |
128 | switching sub-buffers (marking a full one as consumable and switching | |
129 | to an empty one for the following events to be recorded). Knowing this, | |
130 | the following list presents a few practical situations along with how | |
131 | to configure sub-buffers for them when creating a channel in overwrite | |
132 | mode (option:--overwrite option): | |
133 | ||
134 | High event throughput:: | |
135 | In general, prefer bigger sub-buffers to lower the risk of losing | |
136 | events. Having bigger sub-buffers also ensures a lower sub-buffer | |
137 | switching frequency. The number of sub-buffers is only meaningful | |
138 | if the channel is enabled in overwrite mode: in this case, if a | |
139 | sub-buffer overwrite happens, the other sub-buffers | |
140 | are left unaltered. | |
141 | ||
142 | Low event throughput:: | |
143 | In general, prefer smaller sub-buffers since the risk of losing | |
144 | events is already low. Since events happen less frequently, the | |
145 | sub-buffer switching frequency should remain low and thus the | |
146 | tracer's overhead should not be a problem. | |
147 | ||
148 | Low memory system:: | |
149 | If the target system has a low memory limit, prefer fewer first, | |
150 | then smaller sub-buffers. Even if the system is limited in memory, | |
151 | it is recommended to keep the sub-buffers as big as possible to | |
152 | avoid a high sub-buffer switching frequency. | |
153 | ||
154 | In discard mode (option:--discard option), the sub-buffers count | |
155 | parameter is pointless: using two sub-buffers and setting their size | |
156 | according to the requirements of the context is fine. | |
157 | ||
158 | ||
159 | Switch and read timers | |
160 | ~~~~~~~~~~~~~~~~~~~~~~ | |
161 | When a channel's switch timer fires, a sub-buffer switch happens. This | |
162 | timer may be used to ensure that event data is consumed and committed | |
163 | to trace files periodically in case of a low event throughput. | |
164 | ||
165 | It's also convenient when big sub-buffers are used to cope with sporadic | |
166 | high event throughput, even if the throughput is normally lower. | |
167 | ||
168 | By default, a notification mechanism is used to signal a full sub-buffer | |
169 | so that it can be consumed. When such notifications must be avoided, | |
170 | for example in real-time applications, the channel's read timer can be | |
171 | used instead. When the read timer fires, sub-buffers are checked for | |
172 | consumption when they are full. | |
173 | ||
174 | ||
175 | Buffering scheme | |
176 | ~~~~~~~~~~~~~~~~ | |
177 | In the user space tracing domain, two buffering schemes are available | |
178 | when creating a channel: | |
179 | ||
180 | Per-process buffering (option:--buffers-pid option):: | |
181 | Keep one ring buffer per process. | |
182 | ||
183 | Per-user buffering (option:--buffers-uid option):: | |
184 | Keep one ring buffer for all the processes of a single user. | |
185 | ||
186 | The per-process buffering scheme consumes more memory than the per-user | |
187 | option if more than one process is instrumented for LTTng-UST. | |
188 | However, per-process buffering ensures that one process having a high | |
189 | event throughput won't fill all the shared sub-buffers, only its own. | |
190 | ||
191 | The Linux kernel tracing domain only has one available buffering scheme | |
192 | which is to use a single ring buffer for the whole system | |
193 | (option:--buffers-global option). | |
194 | ||
195 | ||
196 | Trace files limit and size | |
197 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
198 | By default, trace files can grow as large as needed. The maximum size | |
199 | of each trace file written by a channel can be set on creation using the | |
200 | option:--tracefile-size option. When such a trace file's size reaches | |
201 | the channel's fixed maximum size, another trace file is created to hold | |
202 | the next recorded events. A file count is appended to each trace file | |
203 | name in this case. | |
204 | ||
205 | If the option:--tracefile-size option is used, the maximum number of | |
206 | created trace files is unlimited. To limit them, the | |
207 | option:--tracefile-count option can be used. This option is always used | |
208 | in conjunction with the option:--tracefile-size option. | |
209 | ||
210 | For example, consider this command: | |
211 | ||
212 | ----------------------------------------------------- | |
213 | lttng enable-channel --kernel --tracefile-size=4096 \ | |
214 | --tracefile-count=32 my-channel | |
215 | ----------------------------------------------------- | |
216 | ||
217 | Here, for each stream, the maximum size of each trace file is | |
218 | 4 kiB and there can be a maximum of 32 different files. When there is | |
219 | no space left in the last file, _trace file rotation_ happens: the first | |
220 | file is cleared and new sub-buffers containing events are written there. | |
221 | ||
222 | ||
223 | include::common-cmd-options-head.txt[] | |
224 | ||
225 | ||
226 | Domain | |
227 | ~~~~~~ | |
228 | One of: | |
229 | ||
230 | option:-k, option:--kernel:: | |
231 | Enable channel in the Linux kernel domain. | |
232 | ||
233 | option:-u, option:--userspace:: | |
234 | Enable channel in the user space domain. | |
235 | ||
236 | ||
237 | Target | |
238 | ~~~~~~ | |
239 | option:-s, option:--session='SESSION':: | |
240 | Create or enable channel in the tracing session named 'SESSION' | |
241 | instead of the current tracing session. | |
242 | ||
243 | ||
244 | Event loss mode | |
245 | ~~~~~~~~~~~~~~~ | |
246 | One of: | |
247 | ||
248 | option:--discard:: | |
249 | Discard events when sub-buffers are full (default). | |
250 | ||
251 | option:--overwrite:: | |
252 | Flight recorder mode: always keep a fixed amount of the latest | |
253 | data. | |
254 | ||
255 | ||
256 | Sub-buffers | |
257 | ~~~~~~~~~~~ | |
258 | option:--num-subbuf='COUNT':: | |
259 | Use 'COUNT' sub-buffers. Rounded up to the next power of two. | |
260 | + | |
261 | Default values: | |
262 | + | |
263 | * `metadata` channel: 2 | |
264 | * Everything else: 4 | |
265 | ||
266 | option:--subbuf-size='SIZE':: | |
267 | Set the individual size of sub-buffers to 'SIZE' bytes. | |
268 | The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported. | |
269 | Rounded up to the next power of two. | |
270 | + | |
271 | The minimum sub-buffer size, for each tracer, is the maximum value | |
272 | between the default below and the system's page size. The following | |
273 | command shows the current system's page size: `getconf PAGE_SIZE`. | |
274 | + | |
275 | Default values: | |
276 | + | |
277 | * option:--userspace and option:--buffers-uid options: `128k` | |
278 | * option:--userspace and option:--buffers-pid options: `4k` | |
279 | * option:--kernel option: `256k` | |
280 | * `metadata` channel: `4k` | |
281 | ||
282 | option:--output='TYPE':: | |
283 | Set channel's output type to 'TYPE'. | |
284 | + | |
285 | Available types: `mmap` (always available) and `splice` (only available | |
286 | with the option:--kernel option). | |
287 | + | |
288 | Default values: | |
289 | + | |
290 | * option:--userspace and option:--buffers-uid options: `mmap` | |
291 | * option:--userspace and option:--buffers-pid options: `mmap` | |
292 | * option:--kernel option: `splice` | |
293 | * `metadata` channel: `mmap` | |
294 | ||
295 | Buffering scheme | |
296 | ~~~~~~~~~~~~~~~~ | |
297 | One of: | |
298 | ||
299 | option:--buffers-global:: | |
300 | Use shared sub-buffers for the whole system (only available with the | |
301 | option:--kernel option). | |
302 | ||
303 | option:--buffers-pid:: | |
304 | Use different sub-buffers for each traced process (only available | |
305 | with the the option:--userspace option). This is the default | |
306 | buffering scheme for user space channels. | |
307 | ||
308 | option:--buffers-uid:: | |
309 | Use shared sub-buffers for all the processes of the user running | |
310 | the command (only available with the option:--userspace option). | |
311 | ||
312 | ||
313 | Trace files | |
314 | ~~~~~~~~~~~ | |
315 | option:--tracefile-count='COUNT':: | |
316 | Limit the number of trace files created by this channel to | |
317 | 'COUNT'. 0 means unlimited. Default: 0. | |
318 | + | |
319 | Use this option in conjunction with the option:--tracefile-size option. | |
320 | + | |
321 | The file count within a stream is appended to each created trace | |
322 | file. If 'COUNT' files are created and more events need to be recorded, | |
323 | the first trace file of the stream is cleared and used again. | |
324 | ||
325 | option:--tracefile-size='SIZE':: | |
326 | Set the maximum size of each trace file written by | |
327 | this channel within a stream to 'SIZE' bytes. 0 means unlimited. | |
328 | Default: 0. | |
329 | + | |
330 | Note: traces generated with this option may inaccurately report | |
331 | discarded events as of CTF 1.8. | |
332 | ||
333 | ||
334 | Timers | |
335 | ~~~~~~ | |
336 | option:--read-timer:: | |
337 | Set the channel's read timer's period to 'PERIODUS' µs. 0 means a | |
338 | disabled read timer. | |
339 | + | |
340 | Default values: | |
341 | + | |
342 | * option:--userspace and option:--buffers-uid options: 0 | |
343 | * option:--userspace and option:--buffers-pid options: 0 | |
344 | * option:--kernel option: 200000 | |
345 | * `metadata` channel: 0 | |
346 | ||
347 | option:--switch-timer='PERIODUS':: | |
348 | Set the channel's switch timer's period to 'PERIODUS' µs. 0 means | |
349 | a disabled switch timer. Default: 0. | |
350 | ||
351 | ||
352 | include::common-cmd-help-options.txt[] | |
353 | ||
354 | ||
355 | include::common-cmd-footer.txt[] | |
356 | ||
357 | ||
358 | SEE ALSO | |
359 | -------- | |
360 | linklttng:lttng-disable-channel(1), | |
361 | linklttng:lttng(1) |