X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng.1.txt;h=0f8f24b9c553bdb53760e6e093af0f7a4aae3c64;hp=55359186f0b603ebd93fd208123150a71affff79;hb=f5511eeafdb40b9589306519633566c3be48756c;hpb=61fa50287dfbd4556b9049145700bcfd68facca2 diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 55359186f..0f8f24b9c 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -1,142 +1,156 @@ lttng(1) ======== +:revdate: 3 May 2021 NAME ---- -lttng - LTTng 2 tracer control command-line tool +lttng - Control LTTng tracing SYNOPSIS -------- [verse] -*lttng* [option:--group='GROUP'] [option:--mi='TYPE'] [option:--no-sessiond | option:--sessiond-path='PATH'] - [option:--quiet | option:-v | option:-vv | option:-vvv] '<>' ['COMMAND OPTIONS'] +*lttng* [option:--group='GROUP'] [option:--mi=**xml**] [option:--no-sessiond | option:--sessiond-path='PATH'] + [option:--quiet | option:-verbose...] '<>' ['COMMAND OPTIONS'] DESCRIPTION ----------- -The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open -source software package used for correlated tracing of the Linux kernel, -user applications, and user libraries. +include::common-intro.txt[] -LTTng consists of Linux kernel modules (for Linux kernel tracing) and -dynamically loaded libraries (for user application and library tracing). +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: -An LTTng _session daemon_, man:lttng-sessiond(8), receives -commands from the command-line interface `lttng` to control the LTTng -tracers. All interactions with the LTTng tracers happen through the -`lttng` tool or through the liblttng-ctl library shipped with the -LTTng-tools package. +* Manages tracing sessions (see man:lttng-concepts(7) to learn more + about tracing sessions). -A _tracing domain_ is a tracer category. There are five available -domains. For some commands, the domain needs to be specified with a -command-line option. The domain options are: +* Controls the various components (like tracers and consumer daemons) of + LTTng. -nloption:-j, nloption:--jul:: - Apply command to the `java.util.logging` (JUL) domain. +* Sends asynchronous notifications to user applications. -nloption:-k, nloption:--kernel:: - Apply command to the Linux kernel domain. +By default, the man:lttng-create(1) command automatically spawns a +session daemon for your Unix user if none is currently running. Override +the path of the session daemon binary to spawn with the +option:--sessiond-path option. Avoid automatically spawning a session +daemon with the option:--no-sessiond option. -nloption:-l, nloption:--log4j:: - Apply command to the https://logging.apache.org/log4j/1.2/[Apache log4j 1.2] - (Java) domain. +NOTE: The LTTng project recommends that you start the session daemon at +boot time for stable and long-term tracing. -nloption:-p, nloption:--python:: - Apply command to the https://www.python.org/[Python] domain. +See man:lttng-concepts(7) to learn more about the foundational concepts +of LTTng. -nloption:-u, nloption:--userspace:: - Apply command to the user space domain (application using - liblttng-ust directly; see man:lttng-ust(3)). +The `lttng` tool offers a subcommand-based command-line interface. The +<> section below lists the available commands. -The LTTng session daemon is a tracing registry which allows the user to -interact with multiple tracers (kernel and user space) within the same -container, a _tracing session_. Traces can be gathered from the Linux -kernel and/or from instrumented applications (see -man:lttng-ust(3)). You can aggregate and read the events of LTTng -traces using man:babeltrace(1). -To trace the Linux kernel, the session daemon needs to be running as -`root`. LTTng uses a _tracing group_ to allow specific users to interact -with the root session daemon. The default tracing group name is -`tracing`. You can use the option:--group option to set the tracing -group name to use. +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. -Session daemons can coexist. You can have a session daemon running as -user Alice that can be used to trace her applications alongside a root -session daemon or a session daemon running as user Bob. +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. -NOTE: It is highly recommended to start the session daemon at boot time -for stable and long-term tracing. +How the `lttng` tool chooses which session daemon to connect to +is as follows: -User applications instrumented with LTTng automatically register to the -root session daemon and to user session daemons. This allows any session -daemon to list the available traceable applications and event sources -(see man:lttng-list(1)). +If your Unix user is `root`:: + Connect to the root session daemon. -By default, the man:lttng-create(1) command automatically spawns a -user session daemon if none is currently running. The -option:--no-sessiond general option can be set to avoid this. +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. + If your Unix user is not part of the tracing group::: + Connect to the session daemon of your Unix user. -OPTIONS -------- -option:-g, option:--group='GROUP':: - Use 'GROUP' as Unix tracing group (default: `tracing`). +The name of the Unix tracing group is one of: -option:-m, option:--mi='TYPE':: - Print the command's result using the machine interface type 'TYPE' - instead of a human-readable output. +With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8)):: + 'GROUP' + -Supported types: `xml`. +In that case, you must use the option:--group='GROUP' option, with +the same 'GROUP' argument, of the `lttng` tool. + +Without the nloption:--group option of the root session daemon:: + `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)). + + +OPTIONS +------- +option:-g 'GROUP', option:--group='GROUP':: + Set the name of the Unix tracing group to 'GROUP' instead of + `tracing`. + -The machine interface (MI) mode converts the traditional pretty-printing -to a machine output syntax. The MI mode provides a change-resistant way -to access information generated by the `lttng` command-line program. +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. + +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. + -When using the MI mode, the data is printed to the standard output. -Errors and warnings are printed on the standard error with the -pretty-print default format. +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 a command, the return value -of the command will be different than 0. In this case, `lttng` does -:not: guarantee the syntax and data validity of the generated MI output. +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. + -For the `xml` MI type, an XML schema definition (XSD) file used for -validation is available: see the `src/common/mi_lttng.xsd` file in -the LTTng-tools source tree. +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. option:-n, option:--no-sessiond:: - Do not automatically spawn a session daemon. + 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. option:-q, option:--quiet:: Suppress all messages, including warnings and errors. ++ +You may :not: use this option with the option:--verbose option. option:--sessiond-path='PATH':: - Set the session daemon binary's absolute path to '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. option:-v, option:--verbose:: Increase verbosity. + -Three levels of verbosity are available, which are triggered by -appending additional `v` letters to the option -(that is, `-vv` and `-vvv`). +Specify this option up to three times to get more levels of verbosity. ++ +You may :not: use this option with the option:--quiet option. Program information ~~~~~~~~~~~~~~~~~~~ -option:-h, option:--help:: - Show help. +include::common-help-option.txt[] option:--list-commands:: - List available commands. - -option:--list-options:: - List available general options. + List available commands and quit. option:-V, option:--version:: - Show version. + Show version and quit. [[commands]] @@ -145,100 +159,100 @@ COMMANDS The following commands also have their own nloption:--help option. -Tracing sessions -~~~~~~~~~~~~~~~~ -man:lttng-create(1):: - {cmd_descr_create}. - -man:lttng-destroy(1):: - {cmd_descr_destroy}. - -man:lttng-load(1):: - {cmd_descr_load}. - -man:lttng-metadata(1):: - {cmd_descr_metadata}. - -man:lttng-save(1):: - {cmd_descr_save}. - -man:lttng-set-session(1):: - {cmd_descr_set_session}. - +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}. +|=== + + +Channel +~~~~~~~ +[options="header"] +|=== +|Command |Description -Channels -~~~~~~~~ -man:lttng-add-context(1):: - {cmd_descr_add_context}. +|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}. +|=== -man:lttng-disable-channel(1):: - {cmd_descr_disable_channel}. -man:lttng-enable-channel(1):: - {cmd_descr_enable_channel}. +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}. +|=== -Event rules +Information ~~~~~~~~~~~ -man:lttng-disable-event(1):: - {cmd_descr_disable_event}. - -man:lttng-enable-event(1):: - {cmd_descr_enable_event}. - - -Status -~~~~~~ -man:lttng-list(1):: - {cmd_descr_list}. - -man:lttng-status(1):: - {cmd_descr_status}. - - -Control -~~~~~~~ -man:lttng-snapshot(1):: - {cmd_descr_snapshot}. - -man:lttng-start(1):: - {cmd_descr_start}. - -man:lttng-stop(1):: - {cmd_descr_stop}. +[options="header"] +|=== +|Command |Description +|man:lttng-list(1) |{cmd_descr_list}. +|=== Resource tracking ~~~~~~~~~~~~~~~~~ -man:lttng-track(1):: - {cmd_descr_track}. +[options="header"] +|=== +|Command |Description -man:lttng-untrack(1):: - {cmd_descr_untrack}. +|man:lttng-track(1) |{cmd_descr_track}. +|man:lttng-untrack(1) |{cmd_descr_untrack}. +|=== + +Trigger +~~~~~~~ +[options="header"] +|=== +|Command |Description +|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 ~~~~~~~~~~~~~ -man:lttng-calibrate(1):: - {cmd_descr_calibrate}. +[options="header"] +|=== +|Command |Description -man:lttng-help(1):: - {cmd_descr_help}. +|man:lttng-help(1) |{cmd_descr_help}. +|man:lttng-version(1) |{cmd_descr_version}. +|man:lttng-view(1) |{cmd_descr_view}. +|=== -man:lttng-version(1):: - {cmd_descr_version}. -man:lttng-view(1):: - {cmd_descr_view}. +include::common-lttng-cmd-after-options.txt[] -include::common-cmd-footer.txt[] +include::common-footer.txt[] SEE ALSO -------- -man:lttng-sessiond(8), +man:lttng-concepts(7) man:lttng-relayd(8), -man:lttng-crash(1), -man:lttng-ust(3), -man:babeltrace(1) +man:lttng-sessiond(8)