Provided by: lttng-tools_2.13.10-1_amd64 bug

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) to learn
       how a user application connects to a session daemon).

       See lttng-concepts(7) 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) utility. Note that, as of LTTng 2.13.10, 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)) 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)
       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) 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) command.

       Start and stop a recording session with the lttng-start(1) and lttng-stop(1) commands.

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

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

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

       Destroy a recording session with the lttng-destroy(1) command.

   Recording session modes
       As documented in lttng-concepts(7), 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)).

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

           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))
           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
               <https://www.ietf.org/rfc/rfc2732.txt>.

           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

       See lttng(1) 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)).

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

   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.10, 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) 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) 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) 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) 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)) to spawn from
           the lttng-create(1) 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-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

       •   LTTng project website <https://lttng.org>

       •   LTTng documentation <https://lttng.org/docs>

       •   LTTng bug tracker <https://bugs.lttng.org>

       •   Git repositories <https://git.lttng.org>

       •   GitHub organization <https://github.com/lttng>

       •   Continuous integration <https://ci.lttng.org/>

       •   Mailing list <https://lists.lttng.org/> for support and development: lttng-
           dev@lists.lttng.org

       •   IRC channel <irc://irc.oftc.net/lttng>: #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
       <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.

SEE ALSO

       lttng(1), lttng-destroy(1), lttng-enable-channel(1), lttng-list(1), lttng-rotate(1),
       lttng-save(1), lttng-set-session(1), lttng-start(1), lttng-status(1), lttng-track(1),
       lttng-concepts(7), lttng-relayd(8), lttng-sessiond(8)