1 lttng-enable-channel(1)
2 =======================
8 lttng-enable-channel - Create or enable LTTng channels
13 Create a Linux kernel channel:
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
17 [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)]
18 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
19 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
20 [option:--monitor-timer='PERIODUS'] [option:--buffers-global]
21 [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
22 [option:--session='SESSION'] 'CHANNEL'
24 Create a user space channel:
27 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
28 [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS']
29 [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid]
30 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
31 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
32 [option:--monitor-timer='PERIODUS']
33 [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
34 [option:--session='SESSION'] 'CHANNEL'
39 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
40 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
45 The `lttng enable-channel` command does one of:
47 * Create a channel named 'CHANNEL'.
49 * Enable one or more disabled channels named 'CHANNEL'
50 (non-option argument, comma-separated).
52 See man:lttng-concepts(7) to learn more about channels.
54 The channel(s) to create or enable belong to:
56 With the option:--session='SESSION' option::
57 The recording session named 'SESSION'.
59 Without the option:--session option::
60 The current recording session (see man:lttng-concepts(7) to learn
61 more about the current recording session).
63 NOTE: The man:lttng-enable-event(1) command can automatically create a
64 default channel when no channel exists for the provided tracing domain.
66 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
68 List the channels of a given recording session with the
69 man:lttng-list(1) and man:lttng-status(1) commands.
71 Disable an enabled channel with the man:lttng-disable-channel(1)
76 As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
77 operations with the `enable-channel` command:
79 * Change an attribute of an existing channel.
81 * Enable a disabled channel once its recording session has been active
82 (started; see man:lttng-start(1)) at least once.
84 * Create a channel once its recording session has been active at least
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 recording session.
94 include::common-lttng-cmd-options-head.txt[]
101 option:-k, option:--kernel::
102 Create or enable channels in the Linux kernel domain.
104 option:-u, option:--userspace::
105 Create or enable channels in the user space domain.
110 option:-s 'SESSION', option:--session='SESSION'::
111 Create or enable channels in the recording session named 'SESSION'
112 instead of the current recording session.
119 option:--buffers-global::
120 Allocate a single set of ring buffers for the whole system.
122 Only available with the option:--kernel option.
124 As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
125 for the Linux kernel tracing domain, but this may change in the future.
127 option:--buffers-pid::
128 Allocate one set of ring buffers (one per CPU) for each instrumented
132 If you connect to the root session daemon::
135 See the ``Session daemon connection'' section of man:lttng(1) to learn
136 how a user application connects to a session daemon.
142 Only available with the option:--userspace option.
144 option:--buffers-uid::
145 Allocate one set of ring buffers (one per CPU) shared by all the
146 instrumented processes of:
149 If you connect to the root session daemon::
152 See the ``Session daemon connection'' section of man:lttng(1) to learn
153 how a user application connects to a session daemon.
159 Only available with the option:--userspace option.
161 As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
162 for the user space tracing domain, but this may change in the future.
165 Event record loss mode
166 ~~~~~~~~~~~~~~~~~~~~~~
167 option:--blocking-timeout='TIMEOUTUS'::
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.
172 'TIMEOUTUS' is one of:
176 Do not block (non-blocking mode).
179 Block forever until a sub-buffer is available to write the event
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.
187 This option is only available with both the option:--userspace and
188 option:--discard options.
193 Discard event records when there's no available sub-buffer.
195 As of LTTng{nbsp}{lttng_version}, this is the default event record loss
196 mode, but this may change in the future.
199 Overwrite the whole sub-buffer containing the oldest event records
200 when there's no available sub-buffer (flight recorder mode).
205 option:--num-subbuf='COUNT'::
206 Use 'COUNT' sub-buffers per ring buffer.
208 The effective value is 'COUNT' rounded up to the next power of two.
212 option:--userspace and option:--buffers-uid options:::
213 +{default_ust_uid_channel_subbuf_num}+
214 option:--userspace and option:--buffers-pid options:::
215 +{default_ust_pid_channel_subbuf_num}+
216 option:--kernel and option:--buffers-global options:::
217 +{default_kernel_channel_subbuf_num}+
218 `metadata` channel:::
219 +{default_metadata_subbuf_num}+
221 option:--output='TYPE'::
222 Set channel's output type to 'TYPE'.
228 Share ring buffers between the tracer and the consumer daemon with
229 the man:mmap(2) system call.
232 Share ring buffers between the tracer and the consumer daemon
233 with the man:splice(2) system call.
235 Only available with the option:--kernel option.
240 option:--userspace and option:--buffers-uid options:::
242 option:--userspace and option:--buffers-pid options:::
244 option:--kernel and option:--buffers-global options:::
246 `metadata` channel:::
249 option:--subbuf-size='SIZE'::
250 Set the size of each sub-buffer to 'SIZE' bytes.
252 The effective value is 'SIZE' rounded up to the next power of two.
254 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
257 The minimum sub-buffer size, for each tracer, is the maximum value
258 between the default below and the system page size (see man:getconf(1)
259 with the `PAGE_SIZE` variable).
263 option:--userspace and option:--buffers-uid options:::
264 +{default_ust_uid_channel_subbuf_size}+
265 option:--userspace and option:--buffers-pid options:::
266 +{default_ust_pid_channel_subbuf_size}+
267 option:--kernel and option:--buffers-global options:::
268 +{default_kernel_channel_subbuf_size}+
269 `metadata` channel:::
270 +{default_metadata_subbuf_size}+
275 option:--tracefile-count='COUNT'::
276 Limit the number of trace files which LTTng writes for this channel
279 'COUNT' set to `0` means ``unlimited''.
281 Default: +{default_channel_tracefile_count}+.
283 You must also use the option:--tracefile-size option with this option.
285 option:--tracefile-size='SIZE'::
286 Set the maximum size of each trace file which LTTng writes for
287 this channel to __SIZE__{nbsp}bytes.
289 'SIZE' set to `0` means ``unlimited''.
291 Default: +{default_channel_tracefile_size}+.
293 NOTE: Data streams which LTTng writes for a channel configured with this
294 option may inaccurately report discarded event records as of
300 option:--monitor-timer='PERIODUS'::
301 Set the period of the monitor timer of the channel to
302 __PERIODUS__{nbsp}µs.
304 Set 'PERIODUS' to `0` to disable the monitor timer.
308 option:--userspace and option:--buffers-uid options:::
309 +{default_ust_uid_channel_monitor_timer}+
310 option:--userspace and option:--buffers-pid options:::
311 +{default_ust_pid_channel_monitor_timer}+
312 option:--kernel and option:--buffers-global options:::
313 +{default_kernel_channel_monitor_timer}+
315 option:--read-timer='PERIODUS'::
316 Set the period of the read timer of the channel to
317 __PERIODUS__{nbsp}µs.
319 Set 'PERIODUS' to `0` to disable the read timer.
323 option:--userspace and option:--buffers-uid options:::
324 +{default_ust_uid_channel_read_timer}+
325 option:--userspace and option:--buffers-pid options:::
326 +{default_ust_pid_channel_read_timer}+
327 option:--kernel and option:--buffers-global options:::
328 +{default_kernel_channel_read_timer}+
329 `metadata` channel:::
330 +{default_metadata_read_timer}+
332 option:--switch-timer='PERIODUS'::
333 Set the period of the switch timer of the channel to
334 __PERIODUS__{nbsp}µs.
336 Set 'PERIODUS' to `0` to disable the switch timer.
340 option:--userspace and option:--buffers-uid options:::
341 +{default_ust_uid_channel_switch_timer}+
342 option:--userspace and option:--buffers-pid options:::
343 +{default_ust_pid_channel_switch_timer}+
344 option:--kernel and option:--buffers-global options:::
345 +{default_kernel_channel_switch_timer}+
346 `metadata` channel:::
347 +{default_metadata_switch_timer}+
350 include::common-lttng-cmd-help-options.txt[]
353 include::common-lttng-cmd-after-options.txt[]
359 .Create a Linux kernel channel with default attributes in the current recording session.
361 The following command line only creates a new channel if `my-channel`
362 doesn't name an existing Linux kernel channel in the current recording
367 $ lttng enable-channel --kernel my-channel
371 .Create a user space channel with a per-process buffering scheme in a specific recording session.
373 See the option:--session and option:--buffers-pid options.
377 $ lttng enable-channel --session=my-session --userspace \
378 --buffers-pid my-channel
382 .Create a Linux kernel channel in the current recording session with four 32-MiB sub-buffers per ring buffer.
384 See the option:--num-subbuf and option:--subbuf-size options.
388 $ lttng enable-channel --kernel my-channel \
389 --num-subbuf=4 --subbuf-size=32M
393 .Create a user space channel in the current recording session with trace file rotation.
395 See the option:--tracefile-count and option:--tracefile-size options.
399 $ lttng enable-channel --userspace my-channel \
400 --tracefile-count=16 --tracefile-size=8M
404 .Enable two user space channels of a specific recording session.
408 $ lttng enable-channel --session=my-session --userspace \
414 include::common-footer.txt[]
420 man:lttng-disable-channel(1),
422 man:lttng-concepts(7)