lttng-enable-channel(1): add usage examples
[lttng-tools.git] / doc / man / lttng-enable-channel.1.txt
CommitLineData
b4867b3b
PP
1lttng-enable-channel(1)
2=======================
bbd159dc 3:revdate: 17 May 2021
b4867b3b
PP
4
5
6NAME
7----
8lttng-enable-channel - Create or enable LTTng channels
9
10
11SYNOPSIS
12--------
13Create a Linux kernel channel:
14
15[verse]
ce19b9ed 16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
26f0c779 17 [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)]
b4867b3b
PP
18 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
19 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
26f0c779
PP
20 [option:--monitor-timer='PERIODUS'] [option:--buffers-global]
21 [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
b4867b3b
PP
22 [option:--session='SESSION'] 'CHANNEL'
23
24Create a user space channel:
25
26[verse]
ce19b9ed 27*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
26f0c779
PP
28 [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS']
29 [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid]
b4867b3b
PP
30 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
31 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
7197e9ec 32 [option:--monitor-timer='PERIODUS']
26f0c779 33 [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
b4867b3b
PP
34 [option:--session='SESSION'] 'CHANNEL'
35
26f0c779 36Enable channel(s):
b4867b3b
PP
37
38[verse]
ce19b9ed 39*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
b4867b3b
PP
40 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
41
42
43DESCRIPTION
44-----------
26f0c779 45The `lttng enable-channel` command does one of:
b4867b3b 46
26f0c779 47* Create a channel named 'CHANNEL'.
b4867b3b 48
26f0c779
PP
49* Enable one or more disabled channels named 'CHANNEL'
50 (non-option argument, comma-separated).
b4867b3b 51
26f0c779 52See man:lttng-concepts(7) to learn more about channels.
b4867b3b 53
26f0c779 54The channel(s) to create or enable belong to:
b4867b3b 55
26f0c779
PP
56With the option:--session='SESSION' option::
57 The tracing session named 'SESSION'.
b4867b3b 58
26f0c779
PP
59Without the option:--session option::
60 The current tracing session (see man:lttng-concepts(7) to learn more
61 about the current tracing session).
b4867b3b 62
26f0c779
PP
63NOTE: The man:lttng-enable-event(1) command can automatically create a
64default channel when no channel exists for the provided tracing domain.
b4867b3b 65
bbd159dc
PP
66See the <<examples,EXAMPLES>> section below for usage examples.
67
26f0c779
PP
68List the channels of a given tracing session with the
69man:lttng-list(1) and man:lttng-status(1) commands.
b4867b3b 70
26f0c779
PP
71Disable an enabled channel with the man:lttng-disable-channel(1)
72command.
b4867b3b 73
26f0c779
PP
74[IMPORTANT]
75====
76As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
77operations with the `enable-channel` command:
b4867b3b 78
26f0c779 79* Change an attribute of an existing channel.
b4867b3b 80
26f0c779
PP
81* Enable a disabled channel once its tracing session has been active
82 (started; see man:lttng-start(1)) at least once.
b4867b3b 83
26f0c779
PP
84* Create a channel once its tracing session has been active at least
85 once.
b4867b3b 86
26f0c779
PP
87* Create a user space channel with a given buffering scheme
88 (option:--buffers-uid or option:--buffers-pid options) and create a
89 second user space channel with a different buffering scheme in the
90 same tracing session.
91====
b4867b3b 92
b4867b3b 93
f5511eea 94include::common-lttng-cmd-options-head.txt[]
b4867b3b 95
b4867b3b 96
26f0c779
PP
97Tracing domain
98~~~~~~~~~~~~~~
99One of:
b4867b3b 100
26f0c779
PP
101option:-k, option:--kernel::
102 Create or enable channels in the Linux kernel domain.
b4867b3b 103
26f0c779
PP
104option:-u, option:--userspace::
105 Create or enable channels in the user space domain.
980bb5fd 106
b4867b3b 107
26f0c779
PP
108Recording target
109~~~~~~~~~~~~~~~~
110option:-s 'SESSION', option:--session='SESSION'::
111 Create or enable channels in the tracing session named 'SESSION'
112 instead of the current tracing session.
b4867b3b
PP
113
114
26f0c779
PP
115Buffering scheme
116~~~~~~~~~~~~~~~~
b4867b3b
PP
117One of:
118
26f0c779
PP
119option:--buffers-global::
120 Allocate a single set of ring buffers for the whole system.
121+
122Only available with the option:--kernel option.
123+
124As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
125for the Linux kernel tracing domain, but this may change in the future.
b4867b3b 126
26f0c779
PP
127option:--buffers-pid::
128 Allocate one set of ring buffers (one per CPU) for each instrumented
129 process of:
130+
131--
132If you connect to the root session daemon::
133 All Unix users.
134+
135See the ``Session daemon connection'' section of man:lttng(1) to learn
136how a user application connects to a session daemon.
b4867b3b 137
26f0c779
PP
138Otherwise::
139 Your Unix user.
140--
141+
142Only available with the option:--userspace option.
b4867b3b 143
26f0c779
PP
144option:--buffers-uid::
145 Allocate one set of ring buffers (one per CPU) shared by all the
146 instrumented processes of:
147+
148--
149If you connect to the root session daemon::
150 Each Unix user.
151+
152See the ``Session daemon connection'' section of man:lttng(1) to learn
153how a user application connects to a session daemon.
154
155Otherwise::
156 Your Unix user.
157--
158+
159Only available with the option:--userspace option.
160+
161As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
162for the user space tracing domain, but this may change in the future.
b4867b3b
PP
163
164
26f0c779
PP
165Event record loss mode
166~~~~~~~~~~~~~~~~~~~~~~
7197e9ec 167option:--blocking-timeout='TIMEOUTUS'::
26f0c779
PP
168 Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs
169 for instrumented applications executed with a set
170 `LTTNG_UST_ALLOW_BLOCKING` environment variable.
171+
172'TIMEOUTUS' is one of:
7197e9ec
PP
173+
174--
26f0c779 175`0` (default)::
7197e9ec
PP
176 Do not block (non-blocking mode).
177
178`inf`::
26f0c779
PP
179 Block forever until a sub-buffer is available to write the event
180 record.
7197e9ec 181
26f0c779
PP
182__N__, a positive value::
183 Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer.
184 After __N__{nbsp}µs, discard the event record.
7197e9ec
PP
185--
186+
26f0c779
PP
187This option is only available with both the option:--userspace and
188option:--discard options.
7197e9ec 189
b4867b3b
PP
190One of:
191
192option:--discard::
26f0c779
PP
193 Discard event records when there's no available sub-buffer.
194+
195As of LTTng{nbsp}{lttng_version}, this is the default event record loss
196mode, but this may change in the future.
b4867b3b
PP
197
198option:--overwrite::
26f0c779
PP
199 Overwrite the whole sub-buffer containing the oldest event records
200 when there's no available sub-buffer (flight recorder mode).
b4867b3b
PP
201
202
203Sub-buffers
204~~~~~~~~~~~
205option:--num-subbuf='COUNT'::
26f0c779
PP
206 Use 'COUNT' sub-buffers per ring buffer.
207+
208The effective value is 'COUNT' rounded up to the next power of two.
b4867b3b
PP
209+
210Default values:
211+
26f0c779
PP
212option:--userspace and option:--buffers-uid options:::
213 +{default_ust_uid_channel_subbuf_num}+
214option:--userspace and option:--buffers-pid options:::
215 +{default_ust_pid_channel_subbuf_num}+
216option:--kernel and option:--buffers-global options:::
217 +{default_kernel_channel_subbuf_num}+
218`metadata` channel:::
219 +{default_metadata_subbuf_num}+
b4867b3b 220
55d7bb02
PP
221option:--output='TYPE'::
222 Set channel's output type to 'TYPE'.
223+
26f0c779
PP
224'TYPE' is one of:
225+
226--
227`mmap`:::
228 Share ring buffers between the tracer and the consumer daemon with
229 the man:mmap(2) system call.
230
231`splice`:::
232 Share ring buffers between the tracer and the consumer daemon
233 with the man:splice(2) system call.
234+
235Only available with the option:--kernel option.
236--
55d7bb02
PP
237+
238Default values:
239+
26f0c779
PP
240option:--userspace and option:--buffers-uid options:::
241 `mmap`
242option:--userspace and option:--buffers-pid options:::
243 `mmap`
244option:--kernel and option:--buffers-global options:::
245 `splice`
246`metadata` channel:::
247 `mmap`
55d7bb02 248
b4867b3b 249option:--subbuf-size='SIZE'::
26f0c779
PP
250 Set the size of each sub-buffer to 'SIZE' bytes.
251+
252The effective value is 'SIZE' rounded up to the next power of two.
253+
254The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
255supported.
b4867b3b
PP
256+
257The minimum sub-buffer size, for each tracer, is the maximum value
26f0c779
PP
258between the default below and the system page size (see man:getconf(1)
259with the `PAGE_SIZE` variable).
b4867b3b
PP
260+
261Default values:
262+
26f0c779
PP
263option:--userspace and option:--buffers-uid options:::
264 +{default_ust_uid_channel_subbuf_size}+
265option:--userspace and option:--buffers-pid options:::
266 +{default_ust_pid_channel_subbuf_size}+
267option:--kernel and option:--buffers-global options:::
268 +{default_kernel_channel_subbuf_size}+
269`metadata` channel:::
270 +{default_metadata_subbuf_size}+
b4867b3b
PP
271
272
273Trace files
274~~~~~~~~~~~
275option:--tracefile-count='COUNT'::
26f0c779
PP
276 Limit the number of trace files which LTTng writes for this channel
277 to 'COUNT'.
b4867b3b 278+
26f0c779 279'COUNT' set to `0` means ``unlimited''.
b4867b3b 280+
26f0c779
PP
281Default: +{default_channel_tracefile_count}+.
282+
283You must also use the option:--tracefile-size option with this option.
b4867b3b
PP
284
285option:--tracefile-size='SIZE'::
26f0c779
PP
286 Set the maximum size of each trace file which LTTng writes for
287 this channel to __SIZE__{nbsp}bytes.
288+
289'SIZE' set to `0` means ``unlimited''.
290+
291Default: +{default_channel_tracefile_size}+.
b4867b3b 292+
26f0c779
PP
293NOTE: Data streams which LTTng writes for a channel configured with this
294option may inaccurately report discarded event records as of
295CTF{nbsp}1.8.
b4867b3b
PP
296
297
298Timers
299~~~~~~
26f0c779
PP
300option:--monitor-timer='PERIODUS'::
301 Set the period of the monitor timer of the channel to
302 __PERIODUS__{nbsp}µs.
303+
304Set 'PERIODUS' to `0` to disable the monitor timer.
961df0d0
PP
305+
306Default values:
307+
26f0c779
PP
308option:--userspace and option:--buffers-uid options:::
309 +{default_ust_uid_channel_monitor_timer}+
310option:--userspace and option:--buffers-pid options:::
311 +{default_ust_pid_channel_monitor_timer}+
312option:--kernel and option:--buffers-global options:::
313 +{default_kernel_channel_monitor_timer}+
314
315option:--read-timer='PERIODUS'::
316 Set the period of the read timer of the channel to
317 __PERIODUS__{nbsp}µs.
318+
319Set 'PERIODUS' to `0` to disable the read timer.
b4867b3b
PP
320+
321Default values:
322+
26f0c779
PP
323option:--userspace and option:--buffers-uid options:::
324 +{default_ust_uid_channel_read_timer}+
325option:--userspace and option:--buffers-pid options:::
326 +{default_ust_pid_channel_read_timer}+
327option:--kernel and option:--buffers-global options:::
328 +{default_kernel_channel_read_timer}+
329`metadata` channel:::
330 +{default_metadata_read_timer}+
b4867b3b
PP
331
332option:--switch-timer='PERIODUS'::
26f0c779
PP
333 Set the period of the switch timer of the channel to
334 __PERIODUS__{nbsp}µs.
335+
336Set 'PERIODUS' to `0` to disable the switch timer.
c93eadad
PP
337+
338Default values:
339+
26f0c779
PP
340option:--userspace and option:--buffers-uid options:::
341 +{default_ust_uid_channel_switch_timer}+
342option:--userspace and option:--buffers-pid options:::
343 +{default_ust_pid_channel_switch_timer}+
344option:--kernel and option:--buffers-global options:::
345 +{default_kernel_channel_switch_timer}+
346`metadata` channel:::
347 +{default_metadata_switch_timer}+
b4867b3b
PP
348
349
f5511eea 350include::common-lttng-cmd-help-options.txt[]
b4867b3b
PP
351
352
f5511eea
PP
353include::common-lttng-cmd-after-options.txt[]
354
355
bbd159dc
PP
356[[examples]]
357EXAMPLES
358--------
359.Create a Linux kernel channel with default attributes in the current tracing session.
360====
361The following command line only creates a new channel if `my-channel`
362doesn't name an existing Linux kernel channel in the current tracing
363session.
364
365[role="term"]
366----
367$ lttng enable-channel --kernel my-channel
368----
369====
370
371.Create a user space channel with a per-process buffering scheme in a specific tracing session.
372====
373See the option:--session and option:--buffers-pid options.
374
375[role="term"]
376----
377$ lttng enable-channel --session=my-session --userspace \
378 --buffers-pid my-channel
379----
380====
381
382.Create a Linux kernel channel in the current tracing session with four 32-MiB sub-buffers per ring buffer.
383====
384See the option:--num-subbuf and option:--subbuf-size options.
385
386[role="term"]
387----
388$ lttng enable-channel --kernel my-channel \
389 --num-subbuf=4 --subbuf-size=32M
390----
391====
392
393.Create a user space channel in the current tracing session with trace file rotation.
394====
395See the option:--tracefile-count and option:--tracefile-size options.
396
397[role="term"]
398----
399$ lttng enable-channel --userspace my-channel \
400 --tracefile-count=16 --tracefile-size=8M
401----
402====
403
404.Enable two user space channels of a specific tracing session.
405====
406[role="term"]
407----
408$ lttng enable-channel --session=my-session --userspace \
409 canal-d,rds
410----
411====
412
413
f5511eea 414include::common-footer.txt[]
b4867b3b
PP
415
416
417SEE ALSO
418--------
491d1539 419man:lttng(1),
26f0c779 420man:lttng-disable-channel(1),
af1c4164
PP
421man:lttng-list(1),
422man:lttng-concepts(7)
This page took 0.053441 seconds and 4 git commands to generate.