lttng(1) ======== :doctype: manpage NAME ---- lttng - LTTng 2.x tracer control command line tool SYNOPSIS -------- *lttng* ['general-options'] 'command' ['command-options'] DESCRIPTION ----------- The LTTng project aims at providing highly efficient tracing tools for Linux. Its tracers help track down performance issues and debug problems involving multiple concurrent processes and threads. Tracing across multiple systems is also possible. The *lttng* command line tool from the lttng-tools package is used to control both kernel and user-space tracing. Every interaction with the tracer should be done by this tool or by the liblttng-ctl library provided by the lttng-tools package. LTTng uses a session daemon (*lttng-sessiond*(8)), acting as a tracing registry, which allows you to interact with multiple tracers (kernel and user-space) inside the same container, a tracing session. Traces can be gathered from the kernel and/or instrumented applications (*lttng-ust*(3)). Aggregating and reading those traces is done using the *babeltrace*(1) text viewer. We introduce the notion of _tracing domains_ which is essentially a type of tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we could see more tracer like for instance an hypervisor. For some commands, you'll need to specify on which domain the command operates (*-u*, *-k*, *-l*, *-j* or *-p*). For instance, the kernel domain must be specified when enabling a kernel event. In order to trace the kernel, the session daemon needs to be running as root. LTTng provides the use of a _tracing group_ (default: *tracing*). Whomever is in that group can interact with the root session daemon and thus trace the kernel. Session daemons can co-exist, meaning that you can have a session daemon running as Alice that can be used to trace her applications along side with a root daemon or even a Bob daemon. We highly recommend starting the session daemon at boot time for stable and long term tracing. Each user-space application instrumented with *lttng-ust*(3) will automatically register with the root session daemon and its user session daemon. This allows each daemon to list the available traceable applications and tracepoints at any given moment (See the *list* command). OPTIONS ------- This program follows the usual GNU command line syntax with long options starting with two dashes. Below is a summary of the available options. *-h, --help*:: Show summary of possible options and commands. *-V, --version*:: Show version. *-v, --verbose*:: Increase verbosity. + Three levels of verbosity are available which are triggered by putting additional *v* to the option (*-vv* or *-vvv*). *-q, --quiet*:: Suppress all messages (even errors). *-g, --group='GROUP'*:: Set unix tracing group name. (default: *tracing*) *-n, --no-sessiond*:: Don't automatically spawn a session daemon. *--sessiond-path='PATH'*:: Set session daemon full binary path. *--list-options*:: Simple listing of lttng commands. *-m, --mi='TYPE'*:: Machine interface + 'TYPE' supported: *xml* + Machine interface (MI) mode converts the traditional pretty printing to a machine output syntax. MI mode provides a format change-resistant way to access information generated via the lttng command line. + When using MI mode, the data is printed on the standard output. Error and warning are printed on the standard error with the pretty print default format. + If any errors occur during the execution of a command, the return value of the command will be different than zero. In this case, lttng does NOT guarantee the syntax and data validity of the generated MI output. + For XML output type, a schema definition (XSD) file used for validation can be found under *src/common/mi_lttng.xsd*. COMMANDS -------- *lttng-add-context*(1):: Add context to event and/or channel *lttng-calibrate*(1):: Quantify LTTng overhead *lttng-create*(1):: Create tracing session *lttng-destroy*(1):: Tear down tracing session *lttng-enable-channel*(1):: Enable tracing channel *lttng-enable-event*(1):: Enable tracing event *lttng-disable-channel*(1):: Disable tracing channel *lttng-disable-event*(1):: Disable tracing event *lttng-list*(1):: List possible tracing options *lttng-set-session*(1):: Set current session name *lttng-snapshot*(1):: Snapshot buffers of current session name *lttng-start*(1):: Start tracing *lttng-stop*(1):: Stop tracing *lttng-version*(1):: Show version information *lttng-view*(1):: Start trace viewer *lttng-save*(1):: Save session configuration *lttng-load*(1):: Load session configuration *lttng-track*(1):: Track specific system resources *lttng-untrack*(1):: Untrack specific system resources Each command also has its own -h, --help option. EXIT STATUS ----------- *0*:: Success *1*:: Command error *2*:: Undefined command *3*:: Fatal error *4*:: Command warning (something went wrong during the command) Any other value above 10, please refer to ** for a detailed list or use *lttng_strerror*() to get a human readable string of the error code. ENVIRONMENT VARIABLES --------------------- Note that all command line options override environment variables. *LTTNG_SESSIOND_PATH*:: Allows one to specify the full session daemon binary path to lttng command line tool. You can also use *--sessiond-path** option having the same effect. *LTTNG_SESSION_CONFIG_XSD_PATH*:: Set the path in which the *session.xsd* session configuration schema may be found. BUGS ---- If you encounter any issues or usability problem, please report it on our mailing list *lttng-dev@lists.lttng.org* to help improve this project or at *https://bugs.lttng.org* which is a bug tracker. RESOURCES --------- A Web site is available at *http://lttng.org* for more information on the LTTng project. You can also find our git tree at *http://git.lttng.org*. Mailing lists for support and development: *lttng-dev@lists.lttng.org*. You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*. COPYRIGHTS ---------- lttng is distributed under the GNU General Public License version 2. See the file *COPYING* for details. THANKS ------ Thanks to Yannick Brosseau without whom this project would never have been so lean and mean! Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases. Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA maintainer) and Jon Bernard for our Debian packages. Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de Montreal for the LTTng journey. AUTHORS ------- lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and David Goulet. More people have since contributed to it. It is currently maintained by Jérémie Galarneau *jeremie.galarneau@efficios.com*. SEE ALSO -------- *babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8), *lttng-crash*(1)