--- name: "lttng-create" section: "1" platform: "linux" package: "lttng-tools" version: "2.13.15-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/lttng-create" --- # lttng-create(1) Create an LTTng recording session ## NAME lttng-create - Create an LTTng recording session ## SYNOPSIS Create a local mode recording session: ``` lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=DIR] [--no-output | --output=DIR | --set-url=file://DIR] ``` Create a network streaming mode recording session: ``` lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=DIR] (--set-url=URL | --ctrl-url=URL --data-url=URL) ``` 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] ``` 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] ``` ## DESCRIPTION The **lttng create** command creates a new recording session for your Unix user within the connected session daemon (see the “Session daemon connection” section of [**lttng**(1)](/lttng/1.md) to learn how a user application connects to a session daemon). See [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn more about recording sessions. Without the *SESSION* argument, LTTng automatically generates a recording session name having the **auto-***YYYYmmdd***-***HHMMSS* form, where *YYYYmmdd* and *HHMMSS* are the creation date and time. *SESSION* may NOT contain the character **/**. Specify the path of the directory containing the shared memory files holding the channel ring buffers with the **--shm-path** option. Specifying a location on an NVRAM file system makes it possible to recover the latest recorded trace data when the system reboots after a crash with the [**lttng-crash**(1)](/lttng-crash/1.md) utility. Note that, as of LTTng 2.13.15, this feature is only available for user space channels. 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)](/lttng-relayd/8.md)) 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** (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. On success, the **create** command sets the current recording session (see [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn more) to the created recording session. See the “EXAMPLES” section below for usage examples. Show the status of the current recording session with the [**lttng-status**(1)](/lttng-status/1.md) command. List the recording sessions of your Unix user, or of all users if your Unix user is **root**, within the connected session daemon with the [**lttng-list**(1)](/lttng-list/1.md) command. Start and stop a recording session with the [**lttng-start**(1)](/lttng-start/1.md) and [**lttng-stop**(1)](/lttng-stop/1.md) commands. Save and load a recording session with the [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md) commands. Allow and disallow specific processes to record events with the [**lttng-track**(1)](/lttng-track/1.md) and [**lttng-untrack**(1)](/lttng-untrack/1.md) commands. Archive the current trace chunk of (rotate) a recording session with the [**lttng-rotate**(1)](/lttng-rotate/1.md) command. Destroy a recording session with the [**lttng-destroy**(1)](/lttng-destroy/1.md) command. ### Recording session modes As documented in [**lttng-concepts**(7)](/lttng-concepts/7.md), LTTng offers four recording session modes: Local mode Write the trace data to the local file system. The trace data output directory is: With the **--no-output** option None: the file system output is disabled. With the **--output**=*DIR* or **--set-url**=**file://***DIR* option The directory *DIR*. 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)](/lttng-relayd/8.md)). 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)](/lttng-relayd/8.md)) when LTTng takes a snapshot (see the [**lttng-snapshot**(1)](/lttng-snapshot/1.md) command). 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. 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. Live mode (**--live** option) Send the trace data over the network to a listening relay daemon (see [**lttng-relayd**(8)](/lttng-relayd/8.md)) 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://**. ### 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. 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). *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. **tcp6** Same as the **net6** protocol. You can only be use this with the **--ctrl-url** and **--data-url** options together. (*HOST* \| *IPADDR*) Hostname or IP address. 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)](/lttng-relayd/8.md)). ## OPTIONS See [**lttng**(1)](/lttng/1.md) for *GENERAL OPTIONS*. ### Mode selection See the “Recording session modes” section above. At most one of: - **--live**\[=*DELAYUS*\] Create the recording session in live mode. The optional *DELAYUS* argument is the maximum time (in s) you can wait for the data to be flushed (sent to the connected LTTng relay daemon). The default value of *DELAYUS* is 1000000. 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 using **net://127.0.0.1**. The session daemon must be able to connect to a listening relay daemon (see [**lttng-relayd**(8)](/lttng-relayd/8.md)). - **--snapshot** Create 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)](/lttng-enable-channel/1.md)). ### Output - **--no-output** Depending on the recording session mode (see the “Recording session modes” section above): Local mode Disable the file system output. Snapshot mode (**--snapshot** option) Do NOT add a snapshot output after creating the recording session. - **-o** *DIR*, **--output**=*DIR* Equivalent to **--set-url**=**file://***DIR*. - **--shm-path**=*DIR* Set the path of the directory containing the shared memory files holding the channel ring buffers to *DIR* on the local file sytem. **Note**\ As of LTTng 2.13.15, LTTng only considers this option for user space (including Java and Python) channels, but this may change in the future. ### 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* Set 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)](/lttng-snapshot/1.md) command immediately after creating the recording session. - **-D** *URL*, **--data-url**=*URL* Set 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)](/lttng-snapshot/1.md) command immediately after creating the recording session. - **-U** *URL*, **--set-url**=*URL* Set 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 (**--snapshot** option) Equivalent to using the *URL* non-option argument of the **add-output** action of the [**lttng-snapshot**(1)](/lttng-snapshot/1.md) 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. **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)](/lttng-help/1.md) 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)](/lttng-sessiond/8.md)) to spawn from the [**lttng-create**(1)](/lttng-create/1.md) 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/1.md). [**lttng-create**(1)](/lttng-create/1.md) and [**lttng-set-session**(1)](/lttng-set-session/1.md) 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)](/lttng-create/1.md) 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)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)). **/etc/lttng/sessions** Directory containing the system-wide saved recording session configurations (see [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)). **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)](/lttng-relayd/8.md) 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 • LTTng project website \ • LTTng documentation \ • LTTng bug tracker \ • Git repositories \ • GitHub organization \ • Continuous integration \ • Mailing list \ for support and development: **lttng-dev@lists.lttng.org** • IRC channel \: **#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 \. See the **LICENSE** \ file for details. ## THANKS Special thanks to Michel Dagenais and the DORSAL laboratory \ 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/1.md), [**lttng-destroy**(1)](/lttng-destroy/1.md), [**lttng-enable-channel**(1)](/lttng-enable-channel/1.md), [**lttng-list**(1)](/lttng-list/1.md), [**lttng-rotate**(1)](/lttng-rotate/1.md), [**lttng-save**(1)](/lttng-save/1.md), [**lttng-set-session**(1)](/lttng-set-session/1.md), [**lttng-start**(1)](/lttng-start/1.md), [**lttng-status**(1)](/lttng-status/1.md), [**lttng-track**(1)](/lttng-track/1.md), [**lttng-concepts**(7)](/lttng-concepts/7.md), [**lttng-relayd**(8)](/lttng-relayd/8.md), [**lttng-sessiond**(8)](/lttng-sessiond/8.md)