X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng.1.txt;h=1b5d5ee31c996a699ad4024c176f81e5520e3b4f;hb=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66;hp=ce37426c79cbea9f32eb410262ab537c918a44c2;hpb=31415f8711b1ee22307f03592a47c06247ba1a11;p=lttng-tools.git diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index ce37426c7..1b5d5ee31 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -1,232 +1,248 @@ 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' ['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_, linklttng: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. -option:-j, option:--jul:: - Apply command to the `java.util.logging` (JUL) domain. +* Sends asynchronous notifications to user applications. -option:-k, option:--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. -option:-l, option:--log4j:: - Apply command to the 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. -option:-p, option:--python:: - Apply command to the Python domain. +See man:lttng-concepts(7) to learn more about the foundational concepts +of LTTng. -option:-u, option:--userspace:: - Apply command to the user space domain. +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 -linklttng:lttng-ust(3)). You can aggregate and read the events of LTTng -traces using linklttng: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 linklttng:lttng-list(1)). +If your Unix user is `root`:: + Connect to the root session daemon. -By default, the linklttng: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]] COMMANDS -------- -The following commands also have their own option:--help option. - - -Tracing sessions -~~~~~~~~~~~~~~~~ -linklttng:lttng-create(1):: - Create a tracing session. - -linklttng:lttng-destroy(1):: - Tear down tracing sessions. - -linklttng:lttng-load(1):: - Load tracing session configurations. - -linklttng:lttng-metadata(1):: - Manage an LTTng tracing session's metadata generation. - -linklttng:lttng-save(1):: - Save tracing session configurations. - -linklttng:lttng-set-session(1):: - Set current tracing session. - +The following commands also have their own nloption:--help option. + + +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 -~~~~~~~~ -linklttng:lttng-add-context(1):: - Add context fields to a channel. +|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}. +|=== -linklttng:lttng-disable-channel(1):: - Disable tracing channels. -linklttng:lttng-enable-channel(1):: - Create or enable tracing channels. +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 ~~~~~~~~~~~ -linklttng:lttng-disable-event(1):: - Disable event rules. - -linklttng:lttng-enable-event(1):: - Create or enable event rules. - - -Status -~~~~~~ -linklttng:lttng-list(1):: - List tracing sessions, domains, channels, and events. - -linklttng:lttng-status(1):: - Get the status of the current tracing session. - - -Control -~~~~~~~ -linklttng:lttng-snapshot(1):: - Snapshot buffers of current tracing session. - -linklttng:lttng-start(1):: - Start tracing. - -linklttng:lttng-stop(1):: - Stop tracing. +[options="header"] +|=== +|Command |Description +|man:lttng-list(1) |{cmd_descr_list}. +|=== Resource tracking ~~~~~~~~~~~~~~~~~ -linklttng:lttng-track(1):: - Track specific system resources. +[options="header"] +|=== +|Command |Description -linklttng:lttng-untrack(1):: - Untrack specific system resources. +|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 ~~~~~~~~~~~~~ -linklttng:lttng-calibrate(1):: - Quantify LTTng overhead. - -linklttng:lttng-help(1):: - Display help information about a command. - -linklttng:lttng-version(1):: - Show version information. +[options="header"] +|=== +|Command |Description -linklttng:lttng-view(1):: - Start trace viewer. +|man:lttng-help(1) |{cmd_descr_help}. +|man:lttng-version(1) |{cmd_descr_version}. +|man:lttng-view(1) |{cmd_descr_view}. +|=== include::common-cmd-footer.txt[] @@ -234,8 +250,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -linklttng:lttng-sessiond(8), -linklttng:lttng-relayd(8), -linklttng:lttng-crash(1), -linklttng:lttng-ust(3), -linklttng:babeltrace(1) +man:lttng-concepts(7) +man:lttng-relayd(8), +man:lttng-sessiond(8)