+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 *<lttng/lttng-error.h>* 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)
projects / lttng-tools.git / commitdiff
