X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng.1.txt;h=fba24cee5c64d5a145b458fd736b2ddd7a0ad099;hb=da39b67ce2828bfc63a02db969048bfe1abd4ca0;hp=808d52dcfb4e652ddc965168b56ed3eabcb7663d;hpb=307a84685f8eac50bba14692d73c69cc276ddc52;p=lttng-tools.git diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 808d52dcf..fba24cee5 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -1,255 +1,284 @@ lttng(1) ======== -:doctype: manpage +:revdate: 12 May 2021 NAME ---- -lttng - LTTng 2.x tracer control command line tool +lttng - Control LTTng tracing SYNOPSIS -------- -*lttng* ['general-options'] 'command' ['command-options'] +[verse] +*lttng* [option:--group='GROUP'] [option:--mi=**xml**] [option:--no-sessiond | option:--sessiond-path='PATH'] + [option:--relayd-path='PATH'] [option:--quiet | option:-verbose...] + '<>' ['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). +include::common-intro.txt[] +The `lttng` command-line tool, as well as any user application linked +with the LTTng control library (`liblttng-ctl`), sends commands to a +listening LTTng session daemon (man:lttng-sessiond(8)). A session +daemon: -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*) +* Manages tracing sessions (see man:lttng-concepts(7) to learn more + about tracing sessions). -*-n, --no-sessiond*:: - Don't automatically spawn a session daemon. +* Controls the various components (like tracers and consumer daemons) of + LTTng. -*--sessiond-path='PATH'*:: - Set session daemon full binary path. +* Sends asynchronous notifications to user applications. -*--list-options*:: - Simple listing of lttng commands. +By default, the man:lttng-create(1) command automatically spawns: -*-m, --mi='TYPE'*:: - Machine interface +* A session daemon for your Unix user if none is currently running. + -'TYPE' supported: *xml* +Override the path of the session daemon binary to spawn with the +option:--sessiond-path option. + -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. +Avoid automatically spawning a session daemon with the +option:--no-sessiond option. + +* A relay daemon (see man:lttng-relayd(8)) if all the following + statements are true: + -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. +-- +* You specify the nloption:--live option. + +* You don't specify any of the nloption:--set-url, nloption:--ctrl-url, + or nloption:--data-url options. + +* No relay daemon is currently listening for TCP connections on + +127.0.0.1:{default_network_viewer_port}+ (default LTTng live reader + connection address and port). +-- + -For XML output type, a schema definition (XSD) file used for validation can be -found under *src/common/mi_lttng.xsd*. +Override the path of the relay daemon binary to spawn with the +option:--relayd-path option. +NOTE: The LTTng project recommends that you start the session daemon at +boot time for stable and long-term tracing. -COMMANDS --------- +See man:lttng-concepts(7) to learn more about the foundational concepts +of LTTng. -*lttng-add-context*(1):: - Add context to event and/or channel +The `lttng` tool offers a subcommand-based command-line interface. The +``<>'' section below lists the available commands. -*lttng-calibrate*(1):: - Quantify LTTng overhead -*lttng-create*(1):: - Create tracing session +Session daemon connection +~~~~~~~~~~~~~~~~~~~~~~~~~ +For most of its commands, the `lttng` tool needs to connect to a +listening LTTng session daemon (man:lttng-sessiond(8)) to control LTTng +tracing. -*lttng-destroy*(1):: - Tear down tracing session +Each Unix user may have its own independent running session daemon. +However, the `lttng` tool must connect to the session daemon of the +`root` user (the root session daemon) to control Linux kernel tracing. -*lttng-enable-channel*(1):: - Enable tracing channel +How the `lttng` tool chooses which session daemon to connect to +is as follows: -*lttng-enable-event*(1):: - Enable tracing event +If your Unix user is `root`:: + Connect to the root session daemon. -*lttng-disable-channel*(1):: - Disable tracing channel +If your Unix user is not `root`:: + If your Unix user is part of the Unix tracing group::: + Try to connect to the root session daemon. ++ +If the root session daemon isn't running, connect to the session daemon +of your Unix user. -*lttng-disable-event*(1):: - Disable tracing event + If your Unix user is not part of the tracing group::: + Connect to the session daemon of your Unix user. -*lttng-list*(1):: - List possible tracing options +The name of the Unix tracing group is one of: -*lttng-set-session*(1):: - Set current session name +With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8)):: + 'GROUP' ++ +In that case, you must use the option:--group='GROUP' option, with +the same 'GROUP' argument, of the `lttng` tool. -*lttng-snapshot*(1):: - Snapshot buffers of current session name +Without the nloption:--group option of the root session daemon:: + `tracing` -*lttng-start*(1):: - Start tracing +LTTng-instrumented user applications automatically register to both the +root and user session daemons. This makes it possible for both session +daemons to list the available instrumented applications and their +instrumentation points (see man:lttng-list(1)). -*lttng-stop*(1):: - Stop tracing -*lttng-version*(1):: - Show version information +OPTIONS +------- +option:-g 'GROUP', option:--group='GROUP':: + Set the name of the Unix tracing group to 'GROUP' instead of + `tracing`. ++ +You must use this option to be able to connect to a root session daemon +(man:lttng-sessiond(8)) which was started with its own +nloption:--group='GROUP' option. -*lttng-view*(1):: - Start trace viewer +option:-m `xml`, option:--mi=++xml++:: + Print the command's result using a stable XML machine interface (MI) + output instead of the default, unstable human-readable output. ++ +With this mode, `lttng` prints the resulting XML document to the +standard output, while it prints any error/warning to the standard error +with an unstable, human-readable format. ++ +If any error occurs during the execution of `lttng`, the command +exits with a status different than{nbsp}0, and `lttng` does +:not: guarantee the syntax and data validity of its MI output. ++ +An XML schema definition (XSD) file used for validation of the MI output +is available: see the `src/common/mi_lttng.xsd` file in the LTTng-tools +source tree. -*lttng-save*(1):: - Save session configuration +option:-n, option:--no-sessiond:: + Do not automatically spawn a session daemon for your Unix user when + running the man:lttng-create(1) command. ++ +You may :not: use this option with the option:--sessiond-path option. -*lttng-load*(1):: - Load session configuration +option:-q, option:--quiet:: + Suppress all messages, including warnings and errors. ++ +You may :not: use this option with the option:--verbose option. -*lttng-track*(1):: - Track specific system resources +option:--sessiond-path='PATH':: + Set the absolute path of the session daemon binary to spawn from the + man:lttng-create(1) command to 'PATH'. ++ +You may :not: use this option with the option:--no-sessiond option. -*lttng-untrack*(1):: - Untrack specific system resources +option:--relayd-path='PATH':: + Set the absolute path of the relay daemon binary to spawn from the + man:lttng-create(1) command to 'PATH'. -Each command also has its own -h, --help option. +option:-v, option:--verbose:: + Increase verbosity. ++ +Specify this option up to three times to get more levels of verbosity. ++ +You may :not: use this option with the option:--quiet option. -EXIT STATUS ------------ -*0*:: - Success +Program information +~~~~~~~~~~~~~~~~~~~ +include::common-help-option.txt[] + +option:--list-commands:: + List available commands and quit. -*1*:: - Command error +option:-V, option:--version:: + Show version and quit. -*2*:: - Undefined command -*3*:: - Fatal error +[[commands]] +COMMANDS +-------- +The following commands also have their own nloption:--help option. -*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. +Tracing session +~~~~~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description +|man:lttng-create(1) |{cmd_descr_create}. +|man:lttng-destroy(1) |{cmd_descr_destroy}. +|man:lttng-disable-rotation(1) |{cmd_descr_disable_rotation}. +|man:lttng-enable-rotation(1) |{cmd_descr_enable_rotation}. +|man:lttng-load(1) |{cmd_descr_load}. +|man:lttng-regenerate(1) |{cmd_descr_regenerate}. +|man:lttng-rotate(1) |{cmd_descr_rotate}. +|man:lttng-save(1) |{cmd_descr_save}. +|man:lttng-set-session(1) |{cmd_descr_set_session}. +|man:lttng-snapshot(1) |{cmd_descr_snapshot}. +|man:lttng-start(1) |{cmd_descr_start}. +|man:lttng-status(1) |{cmd_descr_status}. +|man:lttng-stop(1) |{cmd_descr_stop}. +|=== -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. +Channel +~~~~~~~ +[options="header"] +|=== +|Command |Description -*LTTNG_SESSION_CONFIG_XSD_PATH*:: - Set the path in which the *session.xsd* session configuration schema may be - found. +|man:lttng-add-context(1) |{cmd_descr_add_context}. +|man:lttng-disable-channel(1) |{cmd_descr_disable_channel}. +|man:lttng-enable-channel(1) |{cmd_descr_enable_channel}. +|=== -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. +Recording event rule +~~~~~~~~~~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description +|man:lttng-disable-event(1) |{cmd_descr_disable_event}. +|man:lttng-enable-event(1) |{cmd_descr_enable_event}. +|=== -RESOURCES ---------- -A Web site is available at *http://lttng.org* for more information on the LTTng -project. +Information +~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description -You can also find our git tree at *http://git.lttng.org*. +|man:lttng-list(1) |{cmd_descr_list}. +|=== -Mailing lists for support and development: *lttng-dev@lists.lttng.org*. +Resource tracking +~~~~~~~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description -You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*. +|man:lttng-track(1) |{cmd_descr_track}. +|man:lttng-untrack(1) |{cmd_descr_untrack}. +|=== +Trigger +~~~~~~~ +[options="header"] +|=== +|Command |Description -COPYRIGHTS ----------- -lttng is distributed under the GNU General Public License version 2. See the -file *COPYING* for details. +|man:lttng-add-trigger(1) |{cmd_descr_add_trigger}. +|man:lttng-list-triggers(1) |{cmd_descr_list_triggers}. +|man:lttng-remove-trigger(1) |{cmd_descr_remove_trigger}. +|=== +Miscellaneous +~~~~~~~~~~~~~ +[options="header"] +|=== +|Command |Description -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. +|man:lttng-help(1) |{cmd_descr_help}. +|man:lttng-version(1) |{cmd_descr_version}. +|man:lttng-view(1) |{cmd_descr_view}. +|=== -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. +include::common-lttng-cmd-after-options.txt[] -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*. +include::common-footer.txt[] SEE ALSO -------- -*babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8), -*lttng-crash*(1) +man:lttng-concepts(7) +man:lttng-relayd(8), +man:lttng-sessiond(8)