'\" t .\" Title: lttng-enable-channel .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 14 June 2021 .\" Manual: LTTng Manual .\" Source: LTTng 2.13.11 .\" Language: English .\" .TH "LTTNG\-ENABLE\-CHANN" "1" "14 June 2021" "LTTng 2\&.13\&.11" "LTTng Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" lttng-enable-channel \- Create or enable LTTng channels .SH "SYNOPSIS" .sp Create a Linux kernel channel: .sp .nf \fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-channel\fR \fB--kernel\fR [\fB--discard\fR | \fB--overwrite\fR] [\fB--output\fR=(\fBmmap\fR | \fBsplice\fR)] [\fB--subbuf-size\fR=\fISIZE\fR] [\fB--num-subbuf\fR=\fICOUNT\fR] [\fB--switch-timer\fR=\fIPERIODUS\fR] [\fB--read-timer\fR=\fIPERIODUS\fR] [\fB--monitor-timer\fR=\fIPERIODUS\fR] [\fB--buffers-global\fR] [\fB--tracefile-size\fR=\fISIZE\fR [\fB--tracefile-count\fR=\fICOUNT\fR]] [\fB--session\fR=\fISESSION\fR] \fICHANNEL\fR .fi .sp Create a user space channel: .sp .nf \fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-channel\fR \fB--userspace\fR [\fB--overwrite\fR | [\fB--discard\fR] \fB--blocking-timeout\fR=\fITIMEOUTUS\fR] [\fB--output\fR=\fBmmap\fR] [\fB--buffers-uid\fR | \fB--buffers-pid\fR] [\fB--subbuf-size\fR=\fISIZE\fR] [\fB--num-subbuf\fR=\fICOUNT\fR] [\fB--switch-timer\fR=\fIPERIODUS\fR] [\fB--read-timer\fR=\fIPERIODUS\fR] [\fB--monitor-timer\fR=\fIPERIODUS\fR] [\fB--tracefile-size\fR=\fISIZE\fR [\fB--tracefile-count\fR=\fICOUNT\fR]] [\fB--session\fR=\fISESSION\fR] \fICHANNEL\fR .fi .sp Enable channel(s): .sp .nf \fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-channel\fR (\fB--userspace\fR | \fB--kernel\fR) [\fB--session\fR=\fISESSION\fR] \fICHANNEL\fR[,\fICHANNEL\fR]\&... .fi .SH "DESCRIPTION" .sp The \fBlttng enable-channel\fR command does one of: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Create a channel named \fICHANNEL\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Enable one or more disabled channels named \fICHANNEL\fR (non\-option argument, comma\-separated)\&. .RE .sp See \fBlttng-concepts\fR(7) to learn more about channels\&. .sp The channel(s) to create or enable belong to: .PP With the \fB--session\fR=\fISESSION\fR option .RS 4 The recording session named \fISESSION\fR\&. .RE .PP Without the \fB--session\fR option .RS 4 The current recording session (see \fBlttng-concepts\fR(7) to learn more about the current recording session)\&. .RE .if n \{\ .sp .\} .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .RS 4 .sp The \fBlttng-enable-event\fR(1) command can automatically create a default channel when no channel exists for the provided tracing domain\&. .sp .5v .RE .sp See the \(lqEXAMPLES\(rq section below for usage examples\&. .sp List the channels of a given recording session with the \fBlttng-list\fR(1) and \fBlttng-status\fR(1) commands\&. .sp Disable an enabled channel with the \fBlttng-disable-channel\fR(1) command\&. .if n \{\ .sp .\} .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBImportant\fR .ps -1 .br .RS 4 .sp As of LTTng\ \&2\&.13\&.11, you may NOT perform the following operations with the \fBenable-channel\fR command: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Change an attribute of an existing channel\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Enable a disabled channel once its recording session has been active (started; see \fBlttng-start\fR(1)) at least once\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Create a channel once its recording session has been active at least once\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Create a user space channel with a given buffering scheme (\fB--buffers-uid\fR or \fB--buffers-pid\fR options) and create a second user space channel with a different buffering scheme in the same recording session\&. .RE .sp .5v .RE .SH "OPTIONS" .sp See \fBlttng\fR(1) for \fIGENERAL OPTIONS\fR\&. .SS "Tracing domain" .sp One of: .PP \fB-k\fR, \fB--kernel\fR .RS 4 Create or enable channels in the Linux kernel domain\&. .RE .PP \fB-u\fR, \fB--userspace\fR .RS 4 Create or enable channels in the user space domain\&. .RE .SS "Recording target" .PP \fB-s\fR \fISESSION\fR, \fB--session\fR=\fISESSION\fR .RS 4 Create or enable channels in the recording session named \fISESSION\fR instead of the current recording session\&. .RE .SS "Buffering scheme" .sp One of: .PP \fB--buffers-global\fR .RS 4 Allocate a single set of ring buffers for the whole system\&. .sp Only available with the \fB--kernel\fR option\&. .sp As of LTTng\ \&2\&.13\&.11, this is the default buffering scheme for the Linux kernel tracing domain, but this may change in the future\&. .RE .PP \fB--buffers-pid\fR .RS 4 Allocate one set of ring buffers (one per CPU) for each instrumented process of: .PP If you connect to the root session daemon .RS 4 All Unix users\&. .sp See the \(lqSession daemon connection\(rq section of \fBlttng\fR(1) to learn how a user application connects to a session daemon\&. .RE .PP Otherwise .RS 4 Your Unix user\&. .RE .sp Only available with the \fB--userspace\fR option\&. .RE .PP \fB--buffers-uid\fR .RS 4 Allocate one set of ring buffers (one per CPU) shared by all the instrumented processes of: .PP If you connect to the root session daemon .RS 4 Each Unix user\&. .sp See the \(lqSession daemon connection\(rq section of \fBlttng\fR(1) to learn how a user application connects to a session daemon\&. .RE .PP Otherwise .RS 4 Your Unix user\&. .RE .sp Only available with the \fB--userspace\fR option\&. .sp As of LTTng\ \&2\&.13\&.11, this is the default buffering scheme for the user space tracing domain, but this may change in the future\&. .RE .SS "Event record loss mode" .PP \fB--blocking-timeout\fR=\fITIMEOUTUS\fR .RS 4 Set the channel\(cqs blocking timeout value to \fITIMEOUTUS\fR\ \&\(mcs for instrumented applications executed with a set \fBLTTNG_UST_ALLOW_BLOCKING\fR environment variable\&. .sp \fITIMEOUTUS\fR is one of: .PP \fB0\fR (default) .RS 4 Do not block (non\-blocking mode)\&. .RE .PP \fBinf\fR .RS 4 Block forever until a sub\-buffer is available to write the event record\&. .RE .PP \fIN\fR, a positive value .RS 4 Wait for at most \fIN\fR\ \&\(mcs when trying to write to a sub\-buffer\&. After \fIN\fR\ \&\(mcs, discard the event record\&. .RE .sp This option is only available with both the \fB--userspace\fR and \fB--discard\fR options\&. .RE .sp One of: .PP \fB--discard\fR .RS 4 Discard event records when there\(cqs no available sub\-buffer\&. .sp As of LTTng\ \&2\&.13\&.11, this is the default event record loss mode, but this may change in the future\&. .RE .PP \fB--overwrite\fR .RS 4 Overwrite the whole sub\-buffer containing the oldest event records when there\(cqs no available sub\-buffer (flight recorder mode)\&. .RE .SS "Sub\-buffers" .PP \fB--num-subbuf\fR=\fICOUNT\fR .RS 4 Use \fICOUNT\fR sub\-buffers per ring buffer\&. .sp The effective value is \fICOUNT\fR rounded up to the next power of two\&. .sp Default values: .PP \fB--userspace\fR and \fB--buffers-uid\fR options .RS 4 \fB4\fR .RE .PP \fB--userspace\fR and \fB--buffers-pid\fR options .RS 4 \fB4\fR .RE .PP \fB--kernel\fR and \fB--buffers-global\fR options .RS 4 \fB4\fR .RE .PP \fBmetadata\fR channel .RS 4 \fB2\fR .RE .RE .PP \fB--output\fR=\fITYPE\fR .RS 4 Set channel\(cqs output type to \fITYPE\fR\&. .sp \fITYPE\fR is one of: .PP \fBmmap\fR .RS 4 Share ring buffers between the tracer and the consumer daemon with the \fBmmap\fR(2) system call\&. .RE .PP \fBsplice\fR .RS 4 Share ring buffers between the tracer and the consumer daemon with the \fBsplice\fR(2) system call\&. .sp Only available with the \fB--kernel\fR option\&. .RE .sp Default values: .PP \fB--userspace\fR and \fB--buffers-uid\fR options .RS 4 \fBmmap\fR .RE .PP \fB--userspace\fR and \fB--buffers-pid\fR options .RS 4 \fBmmap\fR .RE .PP \fB--kernel\fR and \fB--buffers-global\fR options .RS 4 \fBsplice\fR .RE .PP \fBmetadata\fR channel .RS 4 \fBmmap\fR .RE .RE .PP \fB--subbuf-size\fR=\fISIZE\fR .RS 4 Set the size of each sub\-buffer to \fISIZE\fR bytes\&. .sp The effective value is \fISIZE\fR rounded up to the next power of two\&. .sp The \fBk\fR\ \&(KiB), \fBM\fR\ \&(MiB), and \fBG\fR\ \&(GiB) suffixes are supported\&. .sp The minimum sub\-buffer size, for each tracer, is the maximum value between the default below and the system page size (see \fBgetconf\fR(1) with the \fBPAGE_SIZE\fR variable)\&. .sp Default values: .PP \fB--userspace\fR and \fB--buffers-uid\fR options .RS 4 \fB524288\fR .RE .PP \fB--userspace\fR and \fB--buffers-pid\fR options .RS 4 \fB16384\fR .RE .PP \fB--kernel\fR and \fB--buffers-global\fR options .RS 4 \fB1048576\fR .RE .PP \fBmetadata\fR channel .RS 4 \fB4096\fR .RE .RE .SS "Trace files" .PP \fB--tracefile-count\fR=\fICOUNT\fR .RS 4 Limit the number of trace files which LTTng writes for this channel to \fICOUNT\fR\&. .sp \fICOUNT\fR set to \fB0\fR means \(lqunlimited\(rq\&. .sp Default: \fB0\fR\&. .sp You must also use the \fB--tracefile-size\fR option with this option\&. .RE .PP \fB--tracefile-size\fR=\fISIZE\fR .RS 4 Set the maximum size of each trace file which LTTng writes for this channel to \fISIZE\fR\ \&bytes\&. .sp \fISIZE\fR set to \fB0\fR means \(lqunlimited\(rq\&. .sp Default: \fB0\fR\&. .if n \{\ .sp .\} .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .RS 4 Data streams which LTTng writes for a channel configured with this option may inaccurately report discarded event records as of CTF\ \&1\&.8\&. .sp .5v .RE .RE .SS "Timers" .PP \fB--monitor-timer\fR=\fIPERIODUS\fR .RS 4 Set the period of the monitor timer of the channel to \fIPERIODUS\fR\ \&\(mcs\&. .sp Set \fIPERIODUS\fR to \fB0\fR to disable the monitor timer\&. .sp Default values: .PP \fB--userspace\fR and \fB--buffers-uid\fR options .RS 4 \fB1000000\fR .RE .PP \fB--userspace\fR and \fB--buffers-pid\fR options .RS 4 \fB1000000\fR .RE .PP \fB--kernel\fR and \fB--buffers-global\fR options .RS 4 \fB1000000\fR .RE .RE .PP \fB--read-timer\fR=\fIPERIODUS\fR .RS 4 Set the period of the read timer of the channel to \fIPERIODUS\fR\ \&\(mcs\&. .sp Set \fIPERIODUS\fR to \fB0\fR to disable the read timer\&. .sp Default values: .PP \fB--userspace\fR and \fB--buffers-uid\fR options .RS 4 \fB0\fR .RE .PP \fB--userspace\fR and \fB--buffers-pid\fR options .RS 4 \fB0\fR .RE .PP \fB--kernel\fR and \fB--buffers-global\fR options .RS 4 \fB200000\fR .RE .PP \fBmetadata\fR channel .RS 4 \fB0\fR .RE .RE .PP \fB--switch-timer\fR=\fIPERIODUS\fR .RS 4 Set the period of the switch timer of the channel to \fIPERIODUS\fR\ \&\(mcs\&. .sp Set \fIPERIODUS\fR to \fB0\fR to disable the switch timer\&. .sp Default values: .PP \fB--userspace\fR and \fB--buffers-uid\fR options .RS 4 \fB0\fR .RE .PP \fB--userspace\fR and \fB--buffers-pid\fR options .RS 4 \fB0\fR .RE .PP \fB--kernel\fR and \fB--buffers-global\fR options .RS 4 \fB0\fR .RE .PP \fBmetadata\fR channel .RS 4 \fB0\fR .RE .RE .SS "Program information" .PP \fB-h\fR, \fB--help\fR .RS 4 Show help\&. .sp This option attempts to launch \fB/usr/bin/man\fR to view this manual page\&. Override the manual pager path with the \fBLTTNG_MAN_BIN_PATH\fR environment variable\&. .RE .PP \fB--list-options\fR .RS 4 List available command options and quit\&. .RE .SH "EXIT STATUS" .PP \fB0\fR .RS 4 Success .RE .PP \fB1\fR .RS 4 Command error .RE .PP \fB2\fR .RS 4 Undefined command .RE .PP \fB3\fR .RS 4 Fatal error .RE .PP \fB4\fR .RS 4 Command warning (something went wrong during the command) .RE .SH "ENVIRONMENT" .PP \fBLTTNG_ABORT_ON_ERROR\fR .RS 4 Set to \fB1\fR to abort the process after the first error is encountered\&. .RE .PP \fBLTTNG_HOME\fR .RS 4 Path to the LTTng home directory\&. .sp Defaults to \fB$HOME\fR\&. .sp Useful when the Unix user running the commands has a non\-writable home directory\&. .RE .PP \fBLTTNG_MAN_BIN_PATH\fR .RS 4 Absolute path to the manual pager to use to read the LTTng command\-line help (with \fBlttng-help\fR(1) or with the \fB--help\fR option) instead of \fB/usr/bin/man\fR\&. .RE .PP \fBLTTNG_SESSION_CONFIG_XSD_PATH\fR .RS 4 Path to the directory containing the \fBsession.xsd\fR recording session configuration XML schema\&. .RE .PP \fBLTTNG_SESSIOND_PATH\fR .RS 4 Absolute path to the LTTng session daemon binary (see \fBlttng-sessiond\fR(8)) to spawn from the \fBlttng-create\fR(1) command\&. .sp The \fB--sessiond-path\fR general option overrides this environment variable\&. .RE .SH "FILES" .PP \fB$LTTNG_HOME/.lttngrc\fR .RS 4 Unix user\(cqs LTTng runtime configuration\&. .sp This is where LTTng stores the name of the Unix user\(cqs current recording session between executions of \fBlttng\fR(1)\&. \fBlttng-create\fR(1) and \fBlttng-set-session\fR(1) set the current recording session\&. .RE .PP \fB$LTTNG_HOME/lttng-traces\fR .RS 4 Default output directory of LTTng traces in local and snapshot modes\&. .sp Override this path with the \fB--output\fR option of the \fBlttng-create\fR(1) command\&. .RE .PP \fB$LTTNG_HOME/.lttng\fR .RS 4 Unix user\(cqs LTTng runtime and configuration directory\&. .RE .PP \fB$LTTNG_HOME/.lttng/sessions\fR .RS 4 Default directory containing the Unix user\(cqs saved recording session configurations (see \fBlttng-save\fR(1) and \fBlttng-load\fR(1))\&. .RE .PP \fB/etc/lttng/sessions\fR .RS 4 Directory containing the system\-wide saved recording session configurations (see \fBlttng-save\fR(1) and \fBlttng-load\fR(1))\&. .RE .if n \{\ .sp .\} .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .RS 4 .sp \fB$LTTNG_HOME\fR defaults to the value of the \fBHOME\fR environment variable\&. .sp .5v .RE .SH "EXAMPLES" .PP \fBExample\ \&1.\ \&Create a Linux kernel channel with default attributes in the current recording session\&.\fR .RS 4 .sp The following command line only creates a new channel if \fBmy-channel\fR doesn\(cqt name an existing Linux kernel channel in the current recording session\&. .sp .if n \{\ .RS 4 .\} .nf $ lttng enable\-channel \-\-kernel my\-channel .fi .if n \{\ .RE .\} .RE .PP \fBExample\ \&2.\ \&Create a user space channel with a per\-process buffering scheme in a specific recording session\&.\fR .RS 4 .sp See the \fB--session\fR and \fB--buffers-pid\fR options\&. .sp .if n \{\ .RS 4 .\} .nf $ lttng enable\-channel \-\-session=my\-session \-\-userspace \e \-\-buffers\-pid my\-channel .fi .if n \{\ .RE .\} .RE .PP \fBExample\ \&3.\ \&Create a Linux kernel channel in the current recording session with four 32\-MiB sub\-buffers per ring buffer\&.\fR .RS 4 .sp See the \fB--num-subbuf\fR and \fB--subbuf-size\fR options\&. .sp .if n \{\ .RS 4 .\} .nf $ lttng enable\-channel \-\-kernel my\-channel \e \-\-num\-subbuf=4 \-\-subbuf\-size=32M .fi .if n \{\ .RE .\} .RE .PP \fBExample\ \&4.\ \&Create a user space channel in the current recording session with trace file rotation\&.\fR .RS 4 .sp See the \fB--tracefile-count\fR and \fB--tracefile-size\fR options\&. .sp .if n \{\ .RS 4 .\} .nf $ lttng enable\-channel \-\-userspace my\-channel \e \-\-tracefile\-count=16 \-\-tracefile\-size=8M .fi .if n \{\ .RE .\} .RE .PP \fBExample\ \&5.\ \&Enable two user space channels of a specific recording session\&.\fR .RS 4 .sp .if n \{\ .RS 4 .\} .nf $ lttng enable\-channel \-\-session=my\-session \-\-userspace \e canal\-d,rds .fi .if n \{\ .RE .\} .RE .SH "RESOURCES" .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} LTTng project website .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} LTTng documentation .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} LTTng bug tracker .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Git repositories .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} GitHub organization .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Continuous integration .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} Mailing list for support and development: \fBlttng-dev@lists.lttng.org\fR .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} IRC channel : \fB#lttng\fR on \fBirc.oftc.net\fR .RE .SH "COPYRIGHT" .sp This program is part of the LTTng\-tools project\&. .sp LTTng\-tools is distributed under the GNU General Public License version\ \&2 \&. See the \fBLICENSE\fR file for details\&. .SH "THANKS" .sp Special thanks to Michel Dagenais and the DORSAL laboratory at \('Ecole Polytechnique de Montr\('eal for the LTTng journey\&. .sp Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases\&. .SH "SEE ALSO" .sp \fBlttng\fR(1), \fBlttng-disable-channel\fR(1), \fBlttng-list\fR(1), \fBlttng-concepts\fR(7)