lttng(1)
========
-:doctype: manpage
+:revdate: 14 June 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...]
+ '<<commands,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).
+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 recording sessions (see man:lttng-concepts(7) to learn more
+ about recording 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
+``<<commands,COMMANDS>>'' 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 *<lttng/lttng-error.h>* for a
-detailed list or use *lttng_strerror*() to get a human readable string
-of the error code.
+Recording 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)
projects / lttng-tools.git / blobdiff