From 307a84685f8eac50bba14692d73c69cc276ddc52 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 31 Aug 2015 16:10:54 -0400 Subject: [PATCH 1/1] doc/man: convert lttng(1) to AsciiDoc MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- doc/man/lttng.1.txt | 255 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 doc/man/lttng.1.txt diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt new file mode 100644 index 000000000..808d52dcf --- /dev/null +++ b/doc/man/lttng.1.txt @@ -0,0 +1,255 @@ +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) -- 2.34.1