lttng-enable-channel(1) ======================= :revdate: 14 June 2021 NAME ---- lttng-enable-channel - Create or enable LTTng channels SYNOPSIS -------- Create a Linux kernel channel: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)] [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] [option:--monitor-timer='PERIODUS'] [option:--buffers-global] [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] [option:--session='SESSION'] 'CHANNEL' Create a user space channel: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS'] [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid] [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] [option:--monitor-timer='PERIODUS'] [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] [option:--session='SESSION'] 'CHANNEL' Enable channel(s): [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel) [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']... DESCRIPTION ----------- The `lttng enable-channel` command does one of: * Create a channel named 'CHANNEL'. * Enable one or more disabled channels named 'CHANNEL' (non-option argument, comma-separated). See man:lttng-concepts(7) to learn more about channels. The channel(s) to create or enable belong to: With the option:--session='SESSION' option:: The recording session named 'SESSION'. Without the option:--session option:: The current recording session (see man:lttng-concepts(7) to learn more about the current recording session). NOTE: The man:lttng-enable-event(1) command can automatically create a default channel when no channel exists for the provided tracing domain. See the ``<>'' section below for usage examples. List the channels of a given recording session with the man:lttng-list(1) and man:lttng-status(1) commands. Disable an enabled channel with the man:lttng-disable-channel(1) command. [IMPORTANT] ==== As of LTTng{nbsp}{lttng_version}, you may :not: perform the following operations with the `enable-channel` command: * Change an attribute of an existing channel. * Enable a disabled channel once its recording session has been active (started; see man:lttng-start(1)) at least once. * Create a channel once its recording session has been active at least once. * Create a user space channel with a given buffering scheme (option:--buffers-uid or option:--buffers-pid options) and create a second user space channel with a different buffering scheme in the same recording session. ==== include::common-lttng-cmd-options-head.txt[] Tracing domain ~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: Create or enable channels in the Linux kernel domain. option:-u, option:--userspace:: Create or enable channels in the user space domain. Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: Create or enable channels in the recording session named 'SESSION' instead of the current recording session. Buffering scheme ~~~~~~~~~~~~~~~~ One of: option:--buffers-global:: Allocate a single set of ring buffers for the whole system. + Only available with the option:--kernel option. + As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme for the Linux kernel tracing domain, but this may change in the future. option:--buffers-pid:: Allocate one set of ring buffers (one per CPU) for each instrumented process of: + -- If you connect to the root session daemon:: All Unix users. + See the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon. Otherwise:: Your Unix user. -- + Only available with the option:--userspace option. option:--buffers-uid:: Allocate one set of ring buffers (one per CPU) shared by all the instrumented processes of: + -- If you connect to the root session daemon:: Each Unix user. + See the ``Session daemon connection'' section of man:lttng(1) to learn how a user application connects to a session daemon. Otherwise:: Your Unix user. -- + Only available with the option:--userspace option. + As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme for the user space tracing domain, but this may change in the future. Event record loss mode ~~~~~~~~~~~~~~~~~~~~~~ option:--blocking-timeout='TIMEOUTUS':: Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs for instrumented applications executed with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable. + 'TIMEOUTUS' is one of: + -- `0` (default):: Do not block (non-blocking mode). `inf`:: Block forever until a sub-buffer is available to write the event record. __N__, a positive value:: Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer. After __N__{nbsp}µs, discard the event record. -- + This option is only available with both the option:--userspace and option:--discard options. One of: option:--discard:: Discard event records when there's no available sub-buffer. + As of LTTng{nbsp}{lttng_version}, this is the default event record loss mode, but this may change in the future. option:--overwrite:: Overwrite the whole sub-buffer containing the oldest event records when there's no available sub-buffer (flight recorder mode). Sub-buffers ~~~~~~~~~~~ option:--num-subbuf='COUNT':: Use 'COUNT' sub-buffers per ring buffer. + The effective value is 'COUNT' rounded up to the next power of two. + Default values: + option:--userspace and option:--buffers-uid options::: +{default_ust_uid_channel_subbuf_num}+ option:--userspace and option:--buffers-pid options::: +{default_ust_pid_channel_subbuf_num}+ option:--kernel and option:--buffers-global options::: +{default_kernel_channel_subbuf_num}+ `metadata` channel::: +{default_metadata_subbuf_num}+ option:--output='TYPE':: Set channel's output type to 'TYPE'. + 'TYPE' is one of: + -- `mmap`::: Share ring buffers between the tracer and the consumer daemon with the man:mmap(2) system call. `splice`::: Share ring buffers between the tracer and the consumer daemon with the man:splice(2) system call. + Only available with the option:--kernel option. -- + Default values: + option:--userspace and option:--buffers-uid options::: `mmap` option:--userspace and option:--buffers-pid options::: `mmap` option:--kernel and option:--buffers-global options::: `splice` `metadata` channel::: `mmap` option:--subbuf-size='SIZE':: Set the size of each sub-buffer to 'SIZE' bytes. + The effective value is 'SIZE' rounded up to the next power of two. + The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are supported. + The minimum sub-buffer size, for each tracer, is the maximum value between the default below and the system page size (see man:getconf(1) with the `PAGE_SIZE` variable). + Default values: + option:--userspace and option:--buffers-uid options::: +{default_ust_uid_channel_subbuf_size}+ option:--userspace and option:--buffers-pid options::: +{default_ust_pid_channel_subbuf_size}+ option:--kernel and option:--buffers-global options::: +{default_kernel_channel_subbuf_size}+ `metadata` channel::: +{default_metadata_subbuf_size}+ Trace files ~~~~~~~~~~~ option:--tracefile-count='COUNT':: Limit the number of trace files which LTTng writes for this channel to 'COUNT'. + 'COUNT' set to `0` means ``unlimited''. + Default: +{default_channel_tracefile_count}+. + You must also use the option:--tracefile-size option with this option. option:--tracefile-size='SIZE':: Set the maximum size of each trace file which LTTng writes for this channel to __SIZE__{nbsp}bytes. + 'SIZE' set to `0` means ``unlimited''. + Default: +{default_channel_tracefile_size}+. + NOTE: Data streams which LTTng writes for a channel configured with this option may inaccurately report discarded event records as of CTF{nbsp}1.8. Timers ~~~~~~ option:--monitor-timer='PERIODUS':: Set the period of the monitor timer of the channel to __PERIODUS__{nbsp}µs. + Set 'PERIODUS' to `0` to disable the monitor timer. + Default values: + option:--userspace and option:--buffers-uid options::: +{default_ust_uid_channel_monitor_timer}+ option:--userspace and option:--buffers-pid options::: +{default_ust_pid_channel_monitor_timer}+ option:--kernel and option:--buffers-global options::: +{default_kernel_channel_monitor_timer}+ option:--read-timer='PERIODUS':: Set the period of the read timer of the channel to __PERIODUS__{nbsp}µs. + Set 'PERIODUS' to `0` to disable the read timer. + Default values: + option:--userspace and option:--buffers-uid options::: +{default_ust_uid_channel_read_timer}+ option:--userspace and option:--buffers-pid options::: +{default_ust_pid_channel_read_timer}+ option:--kernel and option:--buffers-global options::: +{default_kernel_channel_read_timer}+ `metadata` channel::: +{default_metadata_read_timer}+ option:--switch-timer='PERIODUS':: Set the period of the switch timer of the channel to __PERIODUS__{nbsp}µs. + Set 'PERIODUS' to `0` to disable the switch timer. + Default values: + option:--userspace and option:--buffers-uid options::: +{default_ust_uid_channel_switch_timer}+ option:--userspace and option:--buffers-pid options::: +{default_ust_pid_channel_switch_timer}+ option:--kernel and option:--buffers-global options::: +{default_kernel_channel_switch_timer}+ `metadata` channel::: +{default_metadata_switch_timer}+ include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- .Create a Linux kernel channel with default attributes in the current recording session. ==== The following command line only creates a new channel if `my-channel` doesn't name an existing Linux kernel channel in the current recording session. [role="term"] ---- $ lttng enable-channel --kernel my-channel ---- ==== .Create a user space channel with a per-process buffering scheme in a specific recording session. ==== See the option:--session and option:--buffers-pid options. [role="term"] ---- $ lttng enable-channel --session=my-session --userspace \ --buffers-pid my-channel ---- ==== .Create a Linux kernel channel in the current recording session with four 32-MiB sub-buffers per ring buffer. ==== See the option:--num-subbuf and option:--subbuf-size options. [role="term"] ---- $ lttng enable-channel --kernel my-channel \ --num-subbuf=4 --subbuf-size=32M ---- ==== .Create a user space channel in the current recording session with trace file rotation. ==== See the option:--tracefile-count and option:--tracefile-size options. [role="term"] ---- $ lttng enable-channel --userspace my-channel \ --tracefile-count=16 --tracefile-size=8M ---- ==== .Enable two user space channels of a specific recording session. ==== [role="term"] ---- $ lttng enable-channel --session=my-session --userspace \ canal-d,rds ---- ==== include::common-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-disable-channel(1), man:lttng-list(1), man:lttng-concepts(7)