# lttng-create

## NAME



           lttng-create - Create an LTTng tracing session
    


## SYNOPSIS



           Local mode:
    
           **lttng**[_GENERAL OPTIONS_] **create**[_SESSION_] [**--shm-path** =_PATH_]
                 [**--no-output** | **--output** =_PATH_ | **--set-url** =file://_PATH_]
    
           Network streaming mode:
    
           **lttng**[_GENERAL OPTIONS_] **create**[_SESSION_] [**--shm-path** =_PATH_]
                 (**--set-url** =_URL_ | **--ctrl-url** =_URL_ **--data-url** =_URL_)
    
           Snapshot mode:
    
           **lttng**[_GENERAL OPTIONS_] **create**[_SESSION_] **--snapshot**
                 [**--shm-path** =_PATH_] [**--set-url** =_URL_ | **--ctrl-url** =_URL_ **--data-url** =_URL_]
    
           Live mode:
    
           **lttng**[_GENERAL OPTIONS_] **create**[_SESSION_] **--live**[=_DELAYUS_]
                 [**--shm-path** =_PATH_] [**--set-url** =_URL_ | **--ctrl-url** =_URL_ **--data-url** =_URL_]
    


## DESCRIPTION



           The **lttng create** command creates a new tracing session.
    
           A tracing session is a named container of channels, which in turn
           contain event rules. It is domain-agnostic, in that channels and
           event rules can be enabled for the user space tracer and/or the
           Linux kernel tracer.
    
           On execution, an **.lttngrc** file is created, if it does not exist,
           in the user’s home directory. This file contains the name of the
           current tracing session. When creating a new tracing session with
           **lttng create** , the current tracing session is set to this new
           tracing session. The lttng-set-session(1) command can be used to
           set the current tracing session without manually editing the
           **.lttngrc** file.
    
           If _SESSION_ is omitted, a session name is automatically created
           having this form: **auto-YYYYmmdd-HHMMSS**. _SESSION_ **must not** contain
           the character **/**.
    
           The **--shm-path** option can be used to specify the path to the
           shared memory holding the ring buffers. Specifying a location on
           an NVRAM file system makes it possible to retrieve the latest
           recorded trace data when the system reboots after a crash. To view
           the events of ring buffer files after a system crash, use the
           lttng-crash(1) utility.
    
           Tracing sessions are destroyed using the lttng-destroy(1) command.
    
       **Creation modes**
           There are four tracing session modes:
    
           Local mode
               Traces the local system and writes the trace to the local file
               system. The **--output** option specifies the trace path. Using
               **--set-url** =file://_PATH_ is the equivalent of using
               **--output** =_PATH_. The file system output can be disabled using
               the **--no-output** option.
    
               If none of the options mentioned above are used, then the
               trace is written locally in the **$LTTNG_HOME/lttng-traces**
               directory (**$LTTNG_HOME** defaults to **$HOME**).
    
           Network streaming mode
               Traces the local system and sends the trace over the network
               to a listening relay daemon (see lttng-relayd(8)). The **--set-**
               **url** , or **--ctrl-url** and **--data-url** options set the trace output
               destination (see the _URL format_ section below).
    
           Snapshot mode
               Traces the local system without writing the trace to the local
               file system (implicit **--no-output** option). Channels are
               automatically configured to be snapshot-ready on creation (see
               lttng-enable-channel(1)). The lttng-snapshot(1) command is
               used to take snapshots of the current ring buffers. The **--set-**
               **url** , or **--ctrl-url** and **--data-url** options set the default
               snapshot output destination.
    
           Live mode
               Traces the local system, sending trace data to an LTTng relay
               daemon over the network (see lttng-relayd(8)). The **--set-url** ,
               or **--ctrl-url** and **--data-url** options set the trace output
               destination. The live output URLs cannot use the **file://**
               protocol (see the _URL format_ section below).
    
       **URL format**
           The **--set-url** , **--ctrl-url** , and **--data-url** options' arguments are
           URLs.
    
           The format of those URLs is one of:
    
               file://_TRACEPATH_
               _NETPROTO_ ://(_HOST_ | _IPADDR_)[:_CTRLPORT_[:_DATAPORT_]][/_TRACEPATH_]
    
           The **file://** protocol targets the **local file system** and can only be
           used as the **--set-url** option’s argument when the session is
           created in _local_ or _snapshot_ mode.
    
           _TRACEPATH_
               Absolute path to trace files on the local file system.
    
           The other version is available when the session is created in
           _network streaming_ , _snapshot_ , or _live_ mode.
    
           _NETPROTO_
               Network protocol, amongst:
    
               **net**
                   TCP over IPv4; the default values of _CTRLPORT_ and _DATAPORT_
                   are respectively 5342 and 5343.
    
               **net6**
                   TCP over IPv6: same default ports as the **net** protocol.
    
               **tcp**
                   Same as the **net** protocol; can only be used with the
                   **--ctrl-url** and **--data-url** options together.
    
               **tcp6**
                   Same as the **net6** protocol; can only be used with the
                   **--ctrl-url** and **--data-url** options together.
    
           (_HOST_ | _IPADDR_)
               Hostname or IP address (IPv6 address **must** be enclosed in
               brackets (**[** and **]**); see RFC 2732
               <https://www.ietf.org/rfc/rfc2732.txt>).
    
           _CTRLPORT_
               Control port.
    
           _DATAPORT_
               Data port.
    
           _TRACEPATH_
               Path of trace files on the remote file system. This path is
               relative to the base output directory set on the relay daemon
               side; see lttng-relayd(8).
    


## OPTIONS



           General options are described in lttng(1).
    
       **Mode selection**
           **--live**[=_DELAYUS_]
               Create the session in _live mode_.
    
               The optional _DELAYUS_ parameter, given in microseconds, is the
               maximum time the user can wait for the data to be flushed.
               This mode can be set with a network URL (options **--set-url** , or
               **--ctrl-url** and **--data-url**) and must have a relay daemon
               listening (see lttng-relayd(8)).
    
               By default, _DELAYUS_ is 1000000 and the network URL is set to
               **net://127.0.0.1**.
    
           **--snapshot**
               Create the session in _snapshot mode_. This is the equivalent of
               using the **--no-output** option and creating all the channels of
               this new tracing session in overwrite mode with an **mmap** output
               type.
    
       **Output**
           **--no-output**
               In _local mode_ , do not output any trace data.
    
           **-o** _PATH_ , **--output** =_PATH_
               In _local mode_ , set trace output path to _PATH_.
    
           **--shm-path** =_PATH_
               Create shared memory holding buffers at _PATH_.
    
       **URL**
           See the _URL format_ section above for more information about the
           syntax of the following options' _URL_ argument.
    
           **-C** _URL_ , **--ctrl-url** =_URL_
               Set control path URL to _URL_ (must use **--data-url** option also).
    
           **-D** _URL_ , **--data-url** =_URL_
               Set data path URL to _URL_ (must use **--ctrl-url** option also).
    
           **-U** _URL_ , **--set-url** =_URL_
               Set URL destination of the trace data to _URL_. It is persistent
               for the session lifetime. This option sets both data (**--data-**
               **url** option) and control (**--ctrl-url** option) URLs at the same
               time.
    
               In _local_ mode, _URL_ must start with **file://** followed by the
               destination path on the local file system.
    
       **Program information**
           **-h** , **--help**
               Show command help.
    
               This option, like lttng-help(1), attempts to launch
               **/usr/bin/man** to view the command’s man page. The path to the
               man pager can be overridden by the **LTTNG_MAN_BIN_PATH**
               environment variable.
    
           **--list-options**
               List available command options.
    


## ENVIRONMENT VARIABLES



           **LTTNG_ABORT_ON_ERROR**
               Set to 1 to abort the process after the first error is
               encountered.
    
           **LTTNG_HOME**
               Overrides the **$HOME** environment variable. Useful when the user
               running the commands has a non-writable home directory.
    
           **LTTNG_MAN_BIN_PATH**
               Absolute path to the man pager to use for viewing help
               information about LTTng commands (using lttng-help(1) or **lttng**
               **COMMAND --help**).
    
           **LTTNG_SESSION_CONFIG_XSD_PATH**
               Path in which the **session.xsd** session configuration XML schema
               may be found.
    
           **LTTNG_SESSIOND_PATH**
               Full session daemon binary path.
    
               The **--sessiond-path** option has precedence over this
               environment variable.
    
           Note that the lttng-create(1) command can spawn an LTTng session
           daemon automatically if none is running. See lttng-sessiond(8) for
           the environment variables influencing the execution of the session
           daemon.
    


## FILES



           **$LTTNG_HOME/.lttngrc**
               User LTTng runtime configuration.
    
               This is where the per-user current tracing session is stored
               between executions of lttng(1). The current tracing session
               can be set with lttng-set-session(1). See lttng-create(1) for
               more information about tracing sessions.
    
           **$LTTNG_HOME/lttng-traces**
               Default output directory of LTTng traces. This can be
               overridden with the **--output** option of the lttng-create(1)
               command.
    
           **$LTTNG_HOME/.lttng**
               User LTTng runtime and configuration directory.
    
           **$LTTNG_HOME/.lttng/sessions**
               Default location of saved user tracing sessions (see
               lttng-save(1) and lttng-load(1)).
    
           **/usr/local/etc/lttng/sessions**
               System-wide location of saved tracing sessions (see
               lttng-save(1) and lttng-load(1)).
    
               **Note**
    
               **$LTTNG_HOME** defaults to **$HOME** when not explicitly set.
    


## EXIT STATUS



           **0**
               Success
    
           **1**
               Command error
    
           **2**
               Undefined command
    
           **3**
               Fatal error
    
           **4**
               Command warning (something went wrong during the command)
    


## BUGS



           If you encounter any issue or usability problem, please report it
           on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
           tools>.
    


## RESOURCES



           •   LTTng project website <https://lttng.org>
    
           •   LTTng documentation <https://lttng.org/docs>
    
           •   Git repositories <http://git.lttng.org>
    
           •   GitHub organization <http://github.com/lttng>
    
           •   Continuous integration <http://ci.lttng.org/>
    
           •   Mailing list <http://lists.lttng.org> for support and
               development: **lttng-dev@lists.lttng.org**
    
           •   IRC channel <irc://irc.oftc.net/lttng>: **#lttng** on **irc.oftc.net**
    


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


* * *