# lttng-snapshot

## NAME



           lttng-snapshot - Take LTTng snapshots and configure snapshot
           outputs
    


## SYNOPSIS



           Add a snapshot output:
    
           **lttng**[_GENERAL OPTIONS_] **snapshot add-output**[**--max-size** =_SIZE_]
                 [**--name** =_NAME_] [**--session** =_SESSION_]
                 (**--ctrl-url** =_URL_ **--data-url** =_URL_ | _URL_)
    
           Remove a snapshot output:
    
           **lttng**[_GENERAL OPTIONS_] **snapshot del-output**[**--session** =_SESSION_]
                 (_ID_ | _NAME_)
    
           List current snapshot outputs:
    
           **lttng**[_GENERAL OPTIONS_] **snapshot list-output**[**--session** =_SESSION_]
    
           Take a snapshot:
    
           **lttng**[_GENERAL OPTIONS_] **snapshot record**[**--max-size** =_SIZE_]
                 [**--name** =_NAME_] [**--session** =_SESSION_]
                 (**--ctrl-url** =_URL_ **--data-url** =_URL_ | _URL_)
    


## DESCRIPTION



           The **lttng snapshot** command manages the snapshot outputs and takes
           snapshots.
    
           A _snapshot_ is a dump of the current sub-buffers of all the
           channels of a given tracing session. When a snapshot is taken, the
           memory dump is sent to the registered snapshot outputs.
    
           The tracing session should be created in _snapshot mode_ to make
           sure taking snapshots is allowed. This is done at tracing session
           creation time using the lttng-create(1) command.
    
           Note that, when a snapshot is taken, the sub-buffers are not
           cleared. This means that different recorded snapshots may contain
           the same events.
    
       **Snapshot outputs**
           Snapshot outputs are the destinations of snapshot files when a
           snapshot is taken using the **record** action.
    
           As of this version, only one snapshot output is allowed.
    
           A snapshot output can be added using the **add-output** action. The
           output destination URL is set using either the _URL_ positional
           argument, or both the **--ctrl-url** and **--data-url** options. See
           lttng-create(1) to learn more about the URL format.
    
           A name can be assigned to an output when adding it using the
           **--name** option. This name is part of the names of the snapshot
           files written to this output.
    
           By default, the snapshot files can be as big as the sum of the
           sizes of all the sub-buffers or all the channels of the selected
           tracing session. The maximum total size of all the snapshot files
           can be configured using the **--max-size** option.
    
           Snapshot outputs can be listed using the **list-output** action.
    
           Snapshot outputs can be removed using the **del-output** action. The
           configured name can be used when removing an output, or an ID as
           listed by the **list-output** action.
    
       **Taking a snapshot**
           Taking a snapshot of the current tracing session is as easy as:
    
               $ lttng snapshot record
    
           This writes the snapshot files to the configured output. It is
           possible to use a custom, unregistered output at record time using
           the same options supported by the **add-output** action.
    
               **Note**
    
               Before taking a snapshot on a system with a high event
               throughput, it is recommended to first run **lttng stop**(see
               lttng-stop(1)). Otherwise, the snapshot could contain "holes",
               the result of the tracers overwriting unconsumed trace packets
               during the record operation. After the snapshot is recorded,
               the tracers can be started again with **lttng start**(see
               lttng-start(1)).
    


## OPTIONS



           General options are described in lttng(1).
    
       **Target**
           **-s** _SESSION_ , **--session** =_SESSION_
               Take a snapshot of the sub-buffers of the channels contained
               in the tracing session named _SESSION_ instead of the current
               tracing session.
    
       **Snapshot output**
           **-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).
    
           **-m** _SIZE_ , **--max-size** =_SIZE_
               Limit the total size of all the snapshot files written when
               recording a snapshot to _SIZE_ bytes. The **k**(kiB), **M**(MiB), and
               **G**(GiB) suffixes are supported.
    
           **-n** _NAME_ , **--name** =_NAME_
               Assign the name _NAME_ to the snapshot output.
    
       **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.
    


* * *