LTTNG-CREATE(1)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

NAME 💖

lttng-create — create an LTTng recording session. That's the whole thing, bestie, and yes it's from the LTTng Manual.

✨ SYNOPSIS ✨

okay so there's like four whole vibes you can roll with here, and each one has its own receipt:

Create a local mode recording session:

lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=DIR]
      [--no-output | --output=DIR | --set-url=file://DIR]
      [--trace-format=(default | ctf-1.8 | ctf-2)]

Create a network streaming mode recording session:

lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=DIR]
      (--set-url=URL | --ctrl-url=URL --data-url=URL)
      [--trace-format=(default | ctf-1.8 | ctf-2)]

Create a snapshot mode recording session:

lttng [GENERAL OPTIONS] create [SESSION] --snapshot [--shm-path=DIR]
      [--no-output | --output=DIR | --set-url=URL |
       --ctrl-url=URL --data-url=URL]
      [--trace-format=(default | ctf-1.8 | ctf-2)]

Create a live mode recording session:

lttng [GENERAL OPTIONS] create [SESSION] --live[=DELAYUS]
      [--shm-path=DIR] [--set-url=URL | --ctrl-url=URL --data-url=URL]
      [--trace-format=(default | ctf-1.8 | ctf-2)]

🦋 DESCRIPTION 🦋

The lttng create command spins up a brand new recording session for your Unix user, inside the session daemon you're currently connected to. (Wanna know how a user app even gets connected to a session daemon? That's the "Session daemon connection" section of lttng(1), go look, iykyk.)

Also, if you want the full lore on recording sessions, lttng-concepts(7) is right there and it's giving encyclopedia. 📚

No SESSION argument? No problem. LTTng just auto-generates a session name with the auto-YYYYmmdd-HHMMSS form, where YYYYmmdd and HHMMSS are literally the creation date and time. Oh and heads up: SESSION may NOT contain the character /. Sorry bestie, that's just the rules. 💅

Use the --shm-path option to specify the path of the directory holding the shared memory files that carry the channel ring buffers. And here's the iconic part: if you put that on an NVRAM file system, you can recover the latest recorded trace data when the system reboots after a crash, using the lttng-crash(1) utility. 🔥 Note though — as of LTTng 2.15.1</>, this feature is only available for user space channels. Not channels in general, user space channels, periodt.

By default, the create command automatically spawns:

  • A session daemon for your Unix user, if none is currently running.
    • Override the path of the session daemon binary to spawn with the general --sessiond-path option.
    • Avoid automatically spawning a session daemon with the general --no-sessiond option.
  • A relay daemon (see lttng-relayd(8)) if all the following statements are true:
    • You specify the --live option.
    • You don't specify any of the --set-url, --ctrl-url, or --data-url options.
    • No relay daemon is currently listening for TCP connections on 127.0.0.1:5344 (which is the default LTTng live reader connection address and port).

In this case, the create command spawns a relay daemon as such:

lttng-relayd --live-port=tcp://localhost:5344

Override the path of the relay daemon binary to spawn with the general --relayd-path option.

By default, the create command creates a recording session for which LTTng writes traces using the configured default format of lttng-sessiond(8) (peep its --default-trace-format option for the deets). Wanna pick a specific format instead? That's the --trace-format option, boo. 🌈

On success, the create command sets the current recording session (see lttng-concepts(7) to learn more about what that even means) to the recording session it just created. So yeah, it's the main character now. 👑

Usage examples? Scroll down to the "EXAMPLES" section below, it's all there. 💜

Wanna see how your current recording session is doing? That's lttng-status(1).

Wanna list the recording sessions of your Unix user — or of all users if your Unix user is root — within the connected session daemon? That's lttng-list(1). 🎀

Start and stop one or more recording sessions with lttng-start(1) and lttng-stop(1).

Save and load a recording session with lttng-save(1) and lttng-load(1).

Allow and disallow specific processes to record events with lttng-track(1) and lttng-untrack(1).

Archive the current trace chunk of (rotate) a recording session with lttng-rotate(1).

Destroy one or more recording sessions with lttng-destroy(1). 💀

🌸 Recording session modes 🌸

So, as documented over in lttng-concepts(7), LTTng serves four recording session modes. Four! Pick your fighter:

  • Local mode — Write the trace data to the local file system.

The trace data output directory is:

  • With the --no-output option — None. Like, the file system output is disabled. Nothing going nowhere.
  • With the --output=DIR or --set-url=file://DIR option — The directory DIR. Simple as that.
  • Otherwise — A subdirectory, under the $LTTNG_HOME/lttng-traces ($LTTNG_HOME defaults to $HOME) directory, of which the name contains the recording session name and the date/time. ✨
  • Network streaming mode — Send the trace data over the network to a listening relay daemon (see lttng-relayd(8)).

Set the trace output destination with the --set-url option, or with the --ctrl-url and --data-url options (see the "URL format" section below).

  • Snapshot mode (--snapshot option) — Only write the trace data to the local file system or send it to a listening relay daemon (lttng-relayd(8)) when LTTng takes a snapshot (see the lttng-snapshot(1) command). It's the "hold on, wait for it" mode.

With this mode, LTTng:

  • With the --no-output option — Does NOT add any snapshot output to the created recording session.
  • With the --output option, the --set-url option, or the --ctrl-url and --data-url options — Adds a snapshot output named snapshot-1 using the provided path or URL(s) to the created recording session.
  • Otherwise — Adds an automatic snapshot output named snapshot-1 to the created recording session.

That automatic snapshot output is a subdirectory, under the $LTTNG_HOME/lttng-traces ($LTTNG_HOME defaults to $HOME) directory, of which the name contains the recording session name and the date/time. 🍓

  • Live mode (--live option) — Send the trace data over the network to a listening relay daemon (see lttng-relayd(8)) for live reading.

Set the trace output destination with the --set-url=URL option, or with the --ctrl-url=URL and --data-url=URL options (see the "URL format" section below). URL may NOT start with file://. That's a hard no, bestie.

🧚 URL format 🧚

The argument of the --set-url=URL, --ctrl-url=URL, and --data-url=URL options is an URL.

There are two available URL formats. Two flavors, two vibes:

Local format

file://TRACEDIR

The file:// protocol targets the local file system: you may only use such an URL with the --set-url option when you create the recording session in local or snapshot mode (see the "Recording session modes" section above). Not live, not network streaming. Don't try it. 🙈

TRACEDIR : Absolute path to the directory containing the trace data on the local file system.

Network format

NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEDIR]

This format is only available when you create the recording session in network streaming, snapshot (--snapshot), or live (--live) mode (see the "Recording session modes" section above).

NETPROTO : Network protocol, amongst:

  • net — TCP over IPv4.

The default values of CTRLPORT and DATAPORT are respectively 5342 and 5343.

  • net6 — TCP over IPv6.

The default values of CTRLPORT and DATAPORT are respectively 5342 and 5343.

  • tcp — Same as the net protocol.

You may only use this with the --ctrl-url and --data-url options together. Like, they're a package deal.

  • tcp6 — Same as the net6 protocol.

You can only use this with the --ctrl-url and --data-url options together.

(HOST | IPADDR) : Hostname or IP address.

An IPv6 address must be enclosed in square brackets ([ and ]); see RFC 2732.

CTRLPORT : Control TCP port.

DATAPORT : Data TCP port.

TRACEDIR : Path of the directory containing the trace data on the remote file system.

This path is relative to the base output directory of the LTTng relay daemon (see the --output option of lttng-relayd(8)). 🌟

💅 OPTIONS 💅

first off bestie, go peep lttng(1) for the GENERAL OPTIONS — those are the shared ones. 💖 Down here is the lttng create-specific menu.

🎀 Mode selection

See the “Recording session modes” section above — that's the whole vibe of how modes work. You can pick at most one of these, no mixing and matching: ✨

  • --live[=DELAYUS] — creates the recording session in live mode. 🎀

The optional DELAYUS argument is the max time (in µs) you're willing to wait for the data to be flushed — like, actually sent off to the connected LTTng relay daemon. The default value of DELAYUS is 1000000. 🙂‍↕️

Wanna decide where it connects? Set the URL of the relay daemon to connect to with the --set-url option, or with the --ctrl-url and --data-url options, instead of just using net://127.0.0.1.

heads up: the session daemon must be able to connect to a listening relay daemon (see lttng-relayd(8)).
  • --snapshot — creates the recording session in snapshot mode. 📸

This is equivalent to:

  • One of:
    • With the --no-output option: not adding any snapshot output after LTTng creates the recording session.
    • With the --output option, the --set-url option, or the --ctrl-url and --data-url options: adding a snapshot output named snapshot-1 using the provided path or URL(s) immediately after LTTng creates the recording session.
    • Otherwise: adding an automatic snapshot output named snapshot-1 immediately after LTTng creates the recording session.

The automatic snapshot output is a subdirectory, under the $LTTNG_HOME/lttng-traces ($LTTNG_HOME defaults to $HOME) directory, of which the name contains the recording session name and the date/time.

  • Forcing all the channels to be created for the recording session to be configured with the --override and --output=mmap options (see lttng-enable-channel(1)).

✨ Output

  • --no-output — depends on the recording session mode (see the “Recording session modes” section above):
    • Local mode: disable the file system output.
    • Snapshot mode (with the --snapshot option): do NOT add a snapshot output after creating the recording session. 🙈
  • -o DIR, --output=DIR — literally the same thing as --set-url=file://DIR. that's it, that's the whole tea. ✨
  • --shm-path=DIR — sets the path of the directory containing the shared memory files that hold the channel ring buffers to DIR on the local file system. 💾
Note: as of LTTng 2.15.1, LTTng only considers this option for user space (including Java and Python) channels, but this may change in the future.
  • -F FORMAT, --trace-format=FORMAT — sets the output format of the created recording session to FORMAT. FORMAT is one of:

Default: default.

🌸 URL

See the “URL format” section above to learn more about the syntax of the URL argument of the following options. 🧚

  • -C URL, --ctrl-url=URL — sets the control path URL to URL.

You must also use the --data-url option. ⚠️

Not available in local mode (see the “Recording session modes” section above).

In snapshot mode, this is equivalent to using the --ctrl-url option of the add-output action of the lttng-snapshot(1) command immediately after creating the recording session.

  • -D URL, --data-url=URL — sets the trace data path URL to URL.

You must also use the --ctrl-url option. 🔗

Not available in local mode (see the “Recording session modes” section above).

In snapshot mode, this is equivalent to using the --data-url option of the add-output action of the lttng-snapshot(1) command immediately after creating the recording session.

  • -U URL, --set-url=URL — sets the destination URL of the control path and trace data to URL.

This URL remains unchanged as long as the recording session exists. 🔒

Depending on the recording session mode (see the “Recording session modes” section above):

  • Local mode: URL must start with file://, followed with the destination directory path on the local file system.
  • Network streaming and live modes: equivalent to using both the --ctrl-url and --data-url options.
  • Snapshot mode (with the --snapshot option): equivalent to using the URL non-option argument of the add-output action of the lttng-snapshot(1) command immediately after creating the recording session.

💖 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. no second chances bestie 💅
  • LTTNG_HOME — path to the LTTng home directory.

Defaults to $HOME.

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

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

  • 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 at 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 normal mode recording session with a generated name.

$ lttng create

Example 2. Create a normal mode recording session with a custom name.

$ lttng create my-session

Example 3. Create a normal mode recording session with a specific output directory.

See the --output option.

$ lttng create --output=/path/to/traces

Example 4. Create a network streaming mode recording session.

See the “Output directory” section of lttng-relayd(8) to understand where the relay daemon to connect to (10.0.0.242) writes the received traces.

See the --set-url option.

$ lttng create --set-url=net://10.0.0.242/inv4

Example 5. Create a snapshot mode recording session with a default snapshot output.

See the --snapshot option.

$ lttng create --snapshot

Example 6. Create a snapshot mode recording session with a custom snapshot output.

See the --snapshot and --set-url options.

$ lttng create --snapshot \
        --set-url=tcp://192.168.1.102:1234:5678/my-snapshots

Example 7. Create a snapshot mode recording session with no snapshot output.

See the --snapshot and --no-output options.

$ lttng create --snapshot --no-output

Example 8. Create an LTTng live mode recording session with a default relay daemon URL.

See the --live option.

$ lttng create --live

Example 9. Create an LTTng live mode recording session with a custom live timer period and relay daemon URL.

See the --live and --set-url options.

$ lttng create --live=250000 \
               --set-url=tcp://relayd34:4885:4886

Example 10. Create a normal mode recording session with a custom directory containing the ring buffer shared memory files.

See the --shm-path option.

$ lttng create my-session --shm-path=/mnt/nvram2/lttng

⭐ 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 🫶

okay so before we dip, bestie, some people literally carried this whole thing on their backs and they deserve their flowers 💐

  • Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey. like genuinely, the whole origin story? iconic. 👑
  • Also thanks to the Ericsson teams working on tracing, who helped the devs greatly with detailed bug reports and unusual test cases. ngl unusual test cases are how you find out your baby is not as waterproof as you thought 💀 ty for the chaos, it was for science

🌈 SEE ALSO 🌈

go read these next, no cap, they're the whole friend group 🫶

and that's the page, bestie!! ✨ you just read the whole LTTNG-CREATE(1) and I'm so proud of you 🥹 this one is from LTTng 2.15.1, dated 7 October 2025, and it lives its life as LTTNG-CREATE(1). go create a session, slay responsibly, and hydrate 💖🦋🎀

📦 where this page comes from