Provided by: lttng-tools_2.13.10-1_amd64 bug

NAME

       lttng-enable-channel - Create or enable LTTng channels

SYNOPSIS

       Create a Linux kernel channel:

       lttng [GENERAL OPTIONS] enable-channel --kernel
             [--discard | --overwrite] [--output=(mmap | splice)]
             [--subbuf-size=SIZE] [--num-subbuf=COUNT]
             [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
             [--monitor-timer=PERIODUS] [--buffers-global]
             [--tracefile-size=SIZE [--tracefile-count=COUNT]]
             [--session=SESSION] CHANNEL

       Create a user space channel:

       lttng [GENERAL OPTIONS] enable-channel --userspace
             [--overwrite | [--discard] --blocking-timeout=TIMEOUTUS]
             [--output=mmap] [--buffers-uid | --buffers-pid]
             [--subbuf-size=SIZE] [--num-subbuf=COUNT]
             [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
             [--monitor-timer=PERIODUS]
             [--tracefile-size=SIZE [--tracefile-count=COUNT]]
             [--session=SESSION] CHANNEL

       Enable channel(s):

       lttng [GENERAL OPTIONS] enable-channel (--userspace | --kernel)
             [--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 lttng-concepts(7) to learn more about channels.

       The channel(s) to create or enable belong to:

       With the --session=SESSION option
           The recording session named SESSION.

       Without the --session option
           The current recording session (see lttng-concepts(7) to learn more about the current
           recording session).

       Note
           The lttng-enable-event(1) command can automatically create a default channel when no
           channel exists for the provided tracing domain.

       See the “EXAMPLES” section below for usage examples.

       List the channels of a given recording session with the lttng-list(1) and lttng-status(1)
       commands.

       Disable an enabled channel with the lttng-disable-channel(1) command.

       Important
           As of LTTng 2.13.10, 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
               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 (--buffers-uid or
               --buffers-pid options) and create a second user space channel with a different
               buffering scheme in the same recording session.

OPTIONS

       See lttng(1) for GENERAL OPTIONS.

   Tracing domain
       One of:

       -k, --kernel
           Create or enable channels in the Linux kernel domain.

       -u, --userspace
           Create or enable channels in the user space domain.

   Recording target
       -s SESSION, --session=SESSION
           Create or enable channels in the recording session named SESSION instead of the
           current recording session.

   Buffering scheme
       One of:

       --buffers-global
           Allocate a single set of ring buffers for the whole system.

           Only available with the --kernel option.

           As of LTTng 2.13.10, this is the default buffering scheme for the Linux kernel tracing
           domain, but this may change in the future.

       --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 lttng(1) to learn how a user
               application connects to a session daemon.

           Otherwise
               Your Unix user.

           Only available with the --userspace 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 lttng(1) to learn how a user
               application connects to a session daemon.

           Otherwise
               Your Unix user.

           Only available with the --userspace option.

           As of LTTng 2.13.10, this is the default buffering scheme for the user space tracing
           domain, but this may change in the future.

   Event record loss mode
       --blocking-timeout=TIMEOUTUS
           Set the channel’s blocking timeout value to TIMEOUTUS µ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 µs when trying to write to a sub-buffer. After N µs, discard
               the event record.

           This option is only available with both the --userspace and --discard options.

       One of:

       --discard
           Discard event records when there’s no available sub-buffer.

           As of LTTng 2.13.10, this is the default event record loss mode, but this may change
           in the future.

       --overwrite
           Overwrite the whole sub-buffer containing the oldest event records when there’s no
           available sub-buffer (flight recorder mode).

   Sub-buffers
       --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:

           --userspace and --buffers-uid options
               4

           --userspace and --buffers-pid options
               4

           --kernel and --buffers-global options
               4

           metadata channel
               2

       --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 mmap(2)
               system call.

           splice
               Share ring buffers between the tracer and the consumer daemon with the splice(2)
               system call.

               Only available with the --kernel option.

           Default values:

           --userspace and --buffers-uid options
               mmap

           --userspace and --buffers-pid options
               mmap

           --kernel and --buffers-global options
               splice

           metadata channel
               mmap

       --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 (KiB), M (MiB), and G (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 getconf(1) with the PAGE_SIZE variable).

           Default values:

           --userspace and --buffers-uid options
               524288

           --userspace and --buffers-pid options
               16384

           --kernel and --buffers-global options
               1048576

           metadata channel
               4096

   Trace files
       --tracefile-count=COUNT
           Limit the number of trace files which LTTng writes for this channel to COUNT.

           COUNT set to 0 means “unlimited”.

           Default: 0.

           You must also use the --tracefile-size option with this option.

       --tracefile-size=SIZE
           Set the maximum size of each trace file which LTTng writes for this channel to
           SIZE bytes.

           SIZE set to 0 means “unlimited”.

           Default: 0.

           Note
               Data streams which LTTng writes for a channel configured with this option may
               inaccurately report discarded event records as of CTF 1.8.

   Timers
       --monitor-timer=PERIODUS
           Set the period of the monitor timer of the channel to PERIODUS µs.

           Set PERIODUS to 0 to disable the monitor timer.

           Default values:

           --userspace and --buffers-uid options
               1000000

           --userspace and --buffers-pid options
               1000000

           --kernel and --buffers-global options
               1000000

       --read-timer=PERIODUS
           Set the period of the read timer of the channel to PERIODUS µs.

           Set PERIODUS to 0 to disable the read timer.

           Default values:

           --userspace and --buffers-uid options
               0

           --userspace and --buffers-pid options
               0

           --kernel and --buffers-global options
               200000

           metadata channel
               0

       --switch-timer=PERIODUS
           Set the period of the switch timer of the channel to PERIODUS µs.

           Set PERIODUS to 0 to disable the switch timer.

           Default values:

           --userspace and --buffers-uid options
               0

           --userspace and --buffers-pid options
               0

           --kernel and --buffers-global options
               0

           metadata channel
               0

   Program information
       -h, --help
           Show help.

           This option attempts to launch /usr/bin/man to view this manual page. Override the
           manual pager path with the LTTNG_MAN_BIN_PATH environment variable.

       --list-options
           List available command options and quit.

EXIT STATUS

       0
           Success

       1
           Command error

       2
           Undefined command

       3
           Fatal error

       4
           Command warning (something went wrong during the command)

ENVIRONMENT

       LTTNG_ABORT_ON_ERROR
           Set to 1 to abort the process after the first error is encountered.

       LTTNG_HOME
           Path to the LTTng home directory.

           Defaults to $HOME.

           Useful when the Unix user running the commands has a non-writable home directory.

       LTTNG_MAN_BIN_PATH
           Absolute path to the manual pager to use to read the LTTng command-line help (with
           lttng-help(1) or with the --help option) instead of /usr/bin/man.

       LTTNG_SESSION_CONFIG_XSD_PATH
           Path to the directory containing the session.xsd recording session configuration XML
           schema.

       LTTNG_SESSIOND_PATH
           Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from
           the lttng-create(1) command.

           The --sessiond-path general option overrides this environment variable.

FILES

       $LTTNG_HOME/.lttngrc
           Unix user’s LTTng runtime configuration.

           This is where LTTng stores the name of the Unix user’s current recording session
           between executions of lttng(1).  lttng-create(1) and lttng-set-session(1) set the
           current recording session.

       $LTTNG_HOME/lttng-traces
           Default output directory of LTTng traces in local and snapshot modes.

           Override this path with the --output option of the lttng-create(1) command.

       $LTTNG_HOME/.lttng
           Unix user’s LTTng runtime and configuration directory.

       $LTTNG_HOME/.lttng/sessions
           Default directory containing the Unix user’s saved recording session configurations
           (see lttng-save(1) and lttng-load(1)).

       /etc/lttng/sessions
           Directory containing the system-wide saved recording session configurations (see
           lttng-save(1) and lttng-load(1)).

       Note
           $LTTNG_HOME defaults to the value of the HOME environment variable.

EXAMPLES

       Example 1. 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.

               $ lttng enable-channel --kernel my-channel

       Example 2. Create a user space channel with a per-process buffering scheme in a specific
       recording session.

           See the --session and --buffers-pid options.

               $ lttng enable-channel --session=my-session --userspace \
                                      --buffers-pid my-channel

       Example 3. Create a Linux kernel channel in the current recording session with four 32-MiB
       sub-buffers per ring buffer.

           See the --num-subbuf and --subbuf-size options.

               $ lttng enable-channel --kernel my-channel \
                                      --num-subbuf=4 --subbuf-size=32M

       Example 4. Create a user space channel in the current recording session with trace file
       rotation.

           See the --tracefile-count and --tracefile-size options.

               $ lttng enable-channel --userspace my-channel \
                                      --tracefile-count=16 --tracefile-size=8M

       Example 5. Enable two user space channels of a specific recording session.

               $ lttng enable-channel --session=my-session --userspace \
                                      canal-d,rds

RESOURCES

       •   LTTng project website <https://lttng.org>

       •   LTTng documentation <https://lttng.org/docs>

       •   LTTng bug tracker <https://bugs.lttng.org>

       •   Git repositories <https://git.lttng.org>

       •   GitHub organization <https://github.com/lttng>

       •   Continuous integration <https://ci.lttng.org/>

       •   Mailing list <https://lists.lttng.org/> for support and development: lttng-
           dev@lists.lttng.org

       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net

COPYRIGHT

       This program is part of the LTTng-tools project.

       LTTng-tools is distributed under the GNU General Public License version 2
       <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE
       <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

THANKS

       Special thanks to Michel Dagenais and the DORSAL laboratory
       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey.

       Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed
       bug reports and unusual test cases.

SEE ALSO

       lttng(1), lttng-disable-channel(1), lttng-list(1), lttng-concepts(7)