# lttng

## NAME



           lttng - LTTng 2 tracer control command-line tool
    


## SYNOPSIS



           **lttng**[**--group** =_GROUP_] [**--mi** =_TYPE_] [**--no-sessiond** | **--sessiond-path** =_PATH_]
                 [**--quiet** | **-v** | **-vv** | **-vvv**] _COMMAND_ [_COMMAND OPTIONS_]
    


## DESCRIPTION



           The _Linux Trace Toolkit: next generation_ <https://lttng.org/> is
           an open source software package used for correlated tracing of the
           Linux kernel, user applications, and user libraries.
    
           LTTng consists of Linux kernel modules (for Linux kernel tracing)
           and dynamically loaded libraries (for user application and library
           tracing).
    
           An LTTng _session daemon_ , lttng-sessiond(8), receives commands from
           the command-line interface **lttng** to control the LTTng tracers. All
           interactions with the LTTng tracers happen through the **lttng** tool
           or through the liblttng-ctl library shipped with the LTTng-tools
           package.
    
           A _tracing domain_ is a tracer category. There are five available
           domains. For some commands, the domain needs to be specified with
           a command-line option. The domain options are:
    
           **-j** , **--jul**
               Apply command to the **java.util.logging**(JUL) domain.
    
           **-k** , **--kernel**
               Apply command to the Linux kernel domain.
    
           **-l** , **--log4j**
               Apply command to the Apache log4j 1.2
               <https://logging.apache.org/log4j/1.2/> (Java) domain.
    
           **-p** , **--python**
               Apply command to the Python <https://www.python.org/> domain.
    
           **-u** , **--userspace**
               Apply command to the user space domain (application using
               liblttng-ust directly; see lttng-ust(3)).
    
           The LTTng session daemon is a tracing registry which allows the
           user to interact with multiple tracers (kernel and user space)
           within the same container, a _tracing session_. Traces can be
           gathered from the Linux kernel and/or from instrumented
           applications (see lttng-ust(3)). You can aggregate and read the
           events of LTTng traces using **babeltrace**(1).
    
           To trace the Linux kernel, the session daemon needs to be running
           as **root**. LTTng uses a _tracing group_ to allow specific users to
           interact with the root session daemon. The default tracing group
           name is **tracing**. You can use the **--group** option to set the tracing
           group name to use.
    
           Session daemons can coexist. You can have a session daemon running
           as user Alice that can be used to trace her applications alongside
           a root session daemon or a session daemon running as user Bob.
    
               **Note**
    
               It is highly recommended to start the session daemon at boot
               time for stable and long-term tracing.
    
           User applications instrumented with LTTng automatically register
           to the root session daemon and to user session daemons. This
           allows any session daemon to list the available traceable
           applications and event sources (see lttng-list(1)).
    
           By default, the lttng-create(1) command automatically spawns a
           user session daemon if none is currently running. The **--no-**
           **sessiond** general option can be set to avoid this.
    


## OPTIONS



           **-g** _GROUP_ , **--group** =_GROUP_
               Use _GROUP_ as Unix tracing group (default: **tracing**).
    
           **-m** _TYPE_ , **--mi** =_TYPE_
               Print the command’s result using the machine interface type
               _TYPE_ instead of a human-readable output.
    
               Supported types: **xml**.
    
               The machine interface (MI) mode converts the traditional
               pretty-printing to a machine output syntax. The MI mode
               provides a change-resistant way to access information
               generated by the **lttng** command-line program.
    
               When using the MI mode, the data is printed to the standard
               output. Errors and warnings are printed on the standard error
               with the pretty-print default format.
    
               If any error occurs during the execution of a command, the
               return value of the command will be different than 0. In this
               case, **lttng** does NOT guarantee the syntax and data validity of
               the generated MI output.
    
               For the **xml** MI type, an XML schema definition (XSD) file used
               for validation is available: see the **src/common/mi_lttng.xsd**
               file in the LTTng-tools source tree.
    
           **-n** , **--no-sessiond**
               Do not automatically spawn a session daemon.
    
           **-q** , **--quiet**
               Suppress all messages, including warnings and errors.
    
           **--sessiond-path** =_PATH_
               Set the session daemon binary’s absolute path to _PATH_.
    
           **-v** , **--verbose**
               Increase verbosity.
    
               Three levels of verbosity are available, which are triggered
               by appending additional **v** letters to the option (that is, **-vv**
               and **-vvv**).
    
       **Program information**
           **-h** , **--help**
               Show help.
    
           **--list-commands**
               List available commands.
    
           **--list-options**
               List available general options.
    
           **-V** , **--version**
               Show version.
    


## COMMANDS



           The following commands also have their own **--help** option.
    
       **Tracing sessions**
           lttng-create(1)
               Create a tracing session.
    
           lttng-destroy(1)
               Tear down tracing sessions.
    
           lttng-load(1)
               Load tracing session configurations.
    
           lttng-regenerate(1)
               Manage an LTTng tracing session’s data regeneration.
    
           lttng-save(1)
               Save tracing session configurations.
    
           lttng-set-session(1)
               Set current tracing session.
    
       **Channels**
           lttng-add-context(1)
               Add context fields to a channel.
    
           lttng-disable-channel(1)
               Disable tracing channels.
    
           lttng-enable-channel(1)
               Create or enable tracing channels.
    
       **Event rules**
           lttng-disable-event(1)
               Disable event rules.
    
           lttng-enable-event(1)
               Create or enable event rules.
    
       **Status**
           lttng-list(1)
               List tracing sessions, domains, channels, and events.
    
           lttng-status(1)
               Get the status of the current tracing session.
    
       **Control**
           lttng-snapshot(1)
               Snapshot buffers of current tracing session.
    
           lttng-start(1)
               Start tracing.
    
           lttng-stop(1)
               Stop tracing.
    
       **Tracing session rotation**
           lttng-disable-rotation(1)
               Unset a rotation schedule.
    
           lttng-enable-rotation(1)
               Set a rotation schedule.
    
           lttng-rotate(1)
               Archive a tracing session’s current trace chunk.
    
       **Resource tracking**
           lttng-track(1)
               Track specific system resources.
    
           lttng-untrack(1)
               Untrack specific system resources.
    
       **Miscellaneous**
           lttng-help(1)
               Display help information about a command.
    
           lttng-version(1)
               Show version information.
    
           lttng-view(1)
               Start trace viewer.
    


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


* * *