LTTNG-ENABLE-CHANN(1)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

💫 LTTNG-ENABLE-CHANN(1) — lttng-enable-channel 💫

okay bestie, this one lives in section 1 of the LTTng Manual, and it's literally the whole vibe of "make a channel happen." she's long, she's detailed, she's iconic. no cap, read every word, because the details are the moment. 🎀

✨ NAME ✨

lttng-enable-channel — Create or enable LTTng channels

✨ SYNOPSIS ✨

okay so there are three whole ways to run this, and they are NOT interchangeable, so pick your fighter 💅

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]
      [--buffer-ownership=system] [--buffer-allocation=per-cpu]
      [--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]
       [--auto-reclaim-memory=(off | consumed | older-than:AGEUS)]]
      [--output=mmap] [--buffer-ownership=(user | process)]
      [--buffer-allocation=(per-cpu | per-channel)]
      [--buffer-preallocation=(preallocate | on-demand)]
      [--subbuf-size=SIZE] [--num-subbuf=COUNT]
      [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
      [--monitor-timer=PERIODUS] [--watchdog-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 ✨

so lttng enable-channel does exactly one of these two things, and honestly both are a serve:

  • Create a channel named CHANNEL.
  • Enable one or more disabled channels named CHANNEL (that's the non-option argument, comma-separated, bestie — commas are doing the heavy lifting).

go read lttng-concepts(7) if you wanna know more about channels, it's giving foundation.

the channel(s) you're creating or enabling belong to:

  • With the --session=SESSION option — the recording session named SESSION.
  • Without the --session option — the current recording session (and yes, lttng-concepts(7) also explains what "current recording session" means 💖).
Note 📌 the lttng-enable-event(1) command can just casually auto-create a default channel when no channel exists for the tracing domain you gave it. main character energy honestly.

peep the “EXAMPLES” section down below for usage examples, they're cute.

wanna list the channels of a given recording session? that's lttng-list(1) and lttng-status(1), go off 👑.

wanna disable an enabled channel? lttng-disable-channel(1) has you covered.

Important ⚠️ (no literally, important) as of LTTng 2.15.1, you may NOT do any of the following 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 buffer ownership model (--buffer-ownership set to user or process) and then create a second user space channel with a different buffer ownership model in the same recording session.

✨ OPTIONS ✨

the GENERAL OPTIONS live over in lttng(1), so go say hi to them there 🫶

🌈 Tracing domain

pick one, you can't have both:

  • -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.

🦋 Buffer ownership model

one of these, bestie:

  • --buffers-global — Equivalent to --buffer-ownership=system.
Deprecated. 💀 (she's old, she's out, but she's still in the docs, periodt.)
  • --buffer-ownership=MODEL — Depends on MODEL, and it's literally:
    • process — Allocate one set of ring buffers (one per CPU or one for the whole channel, depending on --buffer-allocation) 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.
    • system — Allocate a single set of ring buffers (one per CPU) for the whole system. Only available with the --kernel option. as of LTTng 2.15.1, this is the default buffer ownership model for the Linux kernel tracing domain, but lowkey this may change in the future. 🙈
    • user — Allocate one set of ring buffers (one per CPU or one for the whole channel, depending on --buffer-allocation) 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.15.1, this is the default buffer ownership model for the user space tracing domain, but again, this may change in the future. ✨
  • --buffers-pid — Equivalent to --buffer-ownership=process.
Deprecated. 💀
  • --buffers-uid — Equivalent to --buffer-ownership=user.
Deprecated. 💀

💖 Buffer allocation policy

  • --buffer-allocation=POLICY — Depending on POLICY, allocate one ring buffer for:
    • per-channel — The whole channel. setting --buffer-ownership to user or process determines what entity gets a channel-wise ring buffer. Only available with the --userspace option.
    • per-cpu — Each CPU. setting --buffer-ownership to user, process, or system determines what entity gets a set of per-CPU ring buffers. using this buffer allocation policy implies adding the cpu_id context field, without any way to remove it, for the created channel — similar to running:
$ lttng add-context --session=SESSION --channel=CHANNEL \
                    --type=cpu_id

as of LTTng 2.15.1, this is the default buffer allocation policy, but yeah, this may change in the future. 🌈

🎀 Buffer preallocation policy

  • --buffer-preallocation=POLICY — Depending on POLICY, allocate:
    • preallocate — The full backing memory for all ring buffers when you create the channel. this policy provides consistent performance but uses more memory upfront. Use this policy to optimize instrumented application startup time. as of LTTng 2.15.1, this is the default buffer preallocation policy, but this may change in the future. 👑
    • on-demand — Backing memory for ring buffers incrementally, as needed during tracing. this policy uses less initial memory but may introduce slight performance overhead when allocating new memory during tracing. Only available with the --userspace option.

💜 Automatic memory reclaim

  • --auto-reclaim-memory=STRATEGY — Set the automatic memory reclaim strategy to STRATEGY for the created channel. STRATEGY is one of:
    • off (default) — No automatic memory reclaim. she's chill, she does nothing.
    • consumed — LTTng automatically reclaims the memory of sub-buffers as soon as they're consumed (read). this strategy is not available for channels of recording sessions in snapshot mode or without an output.
    • older-than:AGEUS — LTTng automatically reclaims the memory of sub-buffers of which the closing time exceeds AGEUS µs. the ms (milliseconds), s (seconds), m (minutes), and h (hours) suffixes are supported. this is more or less equivalent to automatically running the lttng-reclaim-memory(1) command. LTTng automatically evaluates the eligibility of sub-buffers for a memory reclaim operation at regular intervals (every half AGEUS µs, but also at least a period defined at build time) and reclaims sub-buffers of which the age of the closing time have exceeded AGEUS µs. more specifically:
      • If AGEUS > last stream activity age — Only sub-buffers of which the age, at the moment of closing them, is greater than AGEUS are eligible for a memory reclaim.
      • If AGEUS < last stream activity age — All sub-buffers are eligible and LTTng flushes the targeted channel so that any open sub-buffer gets closed to become eligible. Only available with the --userspace and --discard options.

🔥 Event record loss mode

  • --blocking-timeout=TIMEOUTUS — Set the blocking timeout value of the channel 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.15.1, 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. (math girlies rise 🧚) default values:
    • --userspace and --buffer-ownership=user options — 4
    • --userspace and --buffer-ownership=process options — 4
    • --kernel and --buffer-ownership=system options — 4
    • metadata channel — 2
  • --output=TYPE — Set the output type of the channel 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 --buffer-ownership=user options — mmap
    • --userspace and --buffer-ownership=process options — mmap
    • --kernel and --buffer-ownership=system options — splice
  • metadata channel — mmap
  • --subbuf-size=SIZE — sets the size of each sub-buffer to SIZE bytes 💅

The effective value is SIZE rounded up to the next power of two (yes, it rounds up, no cap).

The k (KiB), M (MiB), and G (GiB) suffixes are supported.

The minimum sub-buffer size, for each tracer, is the max value between the default listed right below and the system page size (peep getconf(1) with the PAGE_SIZE variable, bestie).

Default values:

  • --userspace and --buffer-ownership=user options — 524288
  • --userspace and --buffer-ownership=process options — 16384
  • --kernel and --buffer-ownership=system options — 1048576
  • metadata channel — 4096

📁 Trace files

  • --tracefile-count=COUNT — caps the number of trace files LTTng writes for this channel at COUNT ✨

COUNT set to 0 means "unlimited".

Default: 0.

You must also use the --tracefile-size option with this option. Like, they're a package deal, fr fr.

  • --tracefile-size=SIZE — sets the max size of each trace file 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 and CTF 2. Not me making it weird, that's just the tea. 🍵

⏱ Timers

  • --monitor-timer=PERIODUS — sets the period of the channel's monitor timer to PERIODUS µs 🦋

Set PERIODUS to 0 to disable the monitor timer.

Default values:

  • --userspace and --buffer-ownership=user options — 1000000
  • --userspace and --buffer-ownership=process options — 1000000
  • --kernel and --buffer-ownership=system options — 1000000
  • --read-timer=PERIODUS — sets the period of the channel's read timer to PERIODUS µs 🌸

Set PERIODUS to 0 to disable the read timer.

Default values:

  • --userspace and --buffer-ownership=user options — 0
  • --userspace and --buffer-ownership=process options — 0
  • --kernel and --buffer-ownership=system options — 200000
  • metadata channel — 0
  • --switch-timer=PERIODUS — sets the period of the channel's switch timer to PERIODUS µs 💫

Set PERIODUS to 0 to disable the switch timer.

Default values:

  • --userspace and --buffer-ownership=user options — 0
  • --userspace and --buffer-ownership=process options — 0
  • --kernel and --buffer-ownership=system options — 0
  • metadata channel — 0
  • --watchdog-timer=PERIODUS — sets the period of the channel's watchdog timer to PERIODUS µs 🐕

Set PERIODUS to 0 to disable the watchdog timer.

You may only use this option with the --userspace and --buffer-ownership=user options. Ik, it's picky, but that's the rule.

Default value: 2000000.

ℹ️ Program information

  • -h, --help — shows 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 — lists the available command options and quits 📋

🚪 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 (been there 🫠).

  • LTTNG_LIST_LEGACY — set to 1 to use the legacy output format (LTTng 2.14 and earlier) for the lttng-list(1) command instead of the modern output format.

Note that the legacy output doesn't show anything related to features introduced after LTTng 2.14. So it's giving throwback, but like, actually.

  • 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_NO_UTF_8 — set to 1 to NOT emit multi-byte UTF-8 sequences, even if the locale claims to support it.
  • 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.

  • LTTNG_TERM_COLOR — controls when to emit terminal SGR codes in the output.

The NO_COLOR environment variable overrides this.

One of:

  • auto (default) — only emit SGR codes when the standard output is connected to a color-capable terminal.
  • always — always emit SGR codes. 🌈
  • never — never emit SGR codes.
  • NO_COLOR — if set and not empty, then it's equivalent to setting LTTNG_TERM_COLOR to never.

See NO_COLOR https://no-color.org/ to learn more.

📂 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 buffer ownership model in a specific recording session.

See the --session and --buffer-ownership options.

$ lttng enable-channel --session=my-session --userspace \
                       --buffer-ownership=process my-channel

💖 Example 3. Create a user space channel with a per-user buffer ownership model (default) and a per-channel buffer allocation policy.

See the --buffer-allocation option.

$ lttng enable-channel --userspace \
                       --buffer-allocation=per-channel my-channel

🍓 Example 4. Create a user space channel with an "on-demand" preallocation policy and an automatic memory reclaim.

See the --buffer-preallocation and --auto-reclaim-memory options.

$ lttng enable-channel --userspace my-channel \
                       --buffer-preallocation=on-demand \
                       --auto-reclaim-memory=older-than:30s

👑 Example 5. 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 6. 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 7. Enable two user space channels of a specific recording session.

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

🧚 RESOURCES

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. Iconic behaviour, honestly. 👑

👀 SEE ALSO

And that's the whole page, bestie — this was LTTng 2.15.1, dated 18 December 2025. Go enable some channels, you absolute legend 💅✨🦋

📦 where this page comes from