From 5d231d824cb0cfba5c4074cc16f09fae8abc146b Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Wed, 11 Nov 2015 14:37:18 -0500 Subject: [PATCH] doc/man: lttng(1): update and standardize content 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/common-cmd-footer.txt | 46 +++++ doc/man/common-footer.txt | 50 +++++ doc/man/lttng.1.txt | 341 ++++++++++++++++------------------ 3 files changed, 258 insertions(+), 179 deletions(-) create mode 100644 doc/man/common-cmd-footer.txt create mode 100644 doc/man/common-footer.txt diff --git a/doc/man/common-cmd-footer.txt b/doc/man/common-cmd-footer.txt new file mode 100644 index 000000000..cbd3c3913 --- /dev/null +++ b/doc/man/common-cmd-footer.txt @@ -0,0 +1,46 @@ +ENVIRONMENT VARIABLES +--------------------- +`LTTNG_HOME`:: + Overrides the `$HOME` environment variable. Useful when the user + running the commands has a non-writable home directory. + +`LTTNG_MAN_BIN_PATH`:: + Absolute path to the man pager to use for viewing help information + about LTTng commands (using linklttng:lttng-help(1) or + `lttng COMMAND --help`). + +`LTTNG_SESSION_CONFIG_XSD_PATH`:: + Path in which the `session.xsd` session configuration XML + schema may be found. + +`LTTNG_SESSIOND_PATH`:: + Full session daemon binary path. ++ +The option:--sessiond-path option has precedence over this +environment variable. + +Note that the linklttng:lttng-create(1) command can spawn an LTTng +session daemon automatically if none is running. See +linklttng:lttng-sessiond(8) for the environment variables influencing +the execution of the session daemon. + + +EXIT STATUS +----------- +*0*:: + Success + +*1*:: + Command error + +*2*:: + Undefined command + +*3*:: + Fatal error + +*4*:: + Command warning (something went wrong during the command) + + +include::common-footer.txt[] diff --git a/doc/man/common-footer.txt b/doc/man/common-footer.txt new file mode 100644 index 000000000..e3ce06c1b --- /dev/null +++ b/doc/man/common-footer.txt @@ -0,0 +1,50 @@ +BUGS +---- +If you encounter any issue or usability problem, please report it on the +LTTng bug tracker: **. + + +RESOURCES +--------- +LTTng project website: **. + +LTTng documentation: **. + +Git repositories: **. + +http://lists.lttng.org[Mailing list] for support and +development: `lttng-dev@lists.lttng.org`. + +IRC channel: `#lttng` on `irc.oftc.net` (http://www.oftc.net/[OFTC]). + + +COPYRIGHTS +---------- +This program is part of the LTTng-tools project. + +LTTng-tools is distributed under the +http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html[GNU General +Public License version 2]. See the +https://github.com/lttng/lttng-tools/blob/master/LICENSE[`LICENSE`] file +for details. + + +THANKS +------ +Special thanks to Michel Dagenais and the +http://www.dorsal.polymtl.ca/[DORSAL laboratory] at École Polytechnique +de Montréal for the LTTng journey. + +Also thanks to the Ericsson teams working on tracing which helped us +greatly with detailed bug reports and unusual test cases. + + +AUTHORS +------- +LTTng-tools was originally written by Mathieu Desnoyers, +Julien Desfossez, and David Goulet. More people have since +contributed to it. + +LTTng-tools is currently maintained by +Jérémie Galarneau +(*mailto:jeremie.galarneau@efficios.com[jeremie.galarneau@efficios.com]*). diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index 808d52dcf..a737e11f3 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -1,255 +1,238 @@ lttng(1) ======== -:doctype: manpage NAME ---- -lttng - LTTng 2.x tracer control command line tool +lttng - LTTng 2 tracer control command-line tool SYNOPSIS -------- -*lttng* ['general-options'] 'command' ['command-options'] +[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'] 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). +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. +LTTng consists of Linux kernel modules (for Linux kernel tracing) and +dynamically loaded libraries (for user application and library tracing). -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. +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. -*-h, --help*:: - Show summary of possible options and commands. +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: -*-V, --version*:: - Show version. +option:-j, option:--jul:: + Apply command to the `java.util.logging` (JUL) domain. -*-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). +option:-k, option:--kernel:: + Apply command to the Linux kernel domain. -*-g, --group='GROUP'*:: - Set unix tracing group name. (default: *tracing*) +option:-l, option:--log4j:: + Apply command to the Apache log4j 1.2 (Java) domain. -*-n, --no-sessiond*:: - Don't automatically spawn a session daemon. +option:-p, option:--python:: + Apply command to the Python domain. -*--sessiond-path='PATH'*:: - Set session daemon full binary path. +option:-u, option:--userspace:: + Apply command to the user space domain. -*--list-options*:: - Simple listing of lttng 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). -*-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*. +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 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. -COMMANDS --------- +NOTE: It is highly recommended to start the session daemon at boot time +for stable and long-term tracing. -*lttng-add-context*(1):: - Add context to event and/or channel +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)). -*lttng-calibrate*(1):: - Quantify LTTng overhead +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. -*lttng-create*(1):: - Create tracing session -*lttng-destroy*(1):: - Tear down tracing session +OPTIONS +------- +option:-g, option:--group='GROUP':: + Use 'GROUP' as Unix tracing group (default: `tracing`). -*lttng-enable-channel*(1):: - Enable tracing channel +option:-m, option:--mi='TYPE':: + Print the command's result using the machine interface type 'TYPE' + instead of a human-readable output. ++ +Supported types: `xml`. ++ +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. ++ +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. ++ +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. ++ +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. -*lttng-enable-event*(1):: - Enable tracing event +option:-n, option:--no-sessiond:: + Do not automatically spawn a session daemon. -*lttng-disable-channel*(1):: - Disable tracing channel +option:-q, option:--quiet:: + Suppress all messages, including warnings and errors. -*lttng-disable-event*(1):: - Disable tracing event +option:--sessiond-path='PATH':: + Set the session daemon binary's absolute path to 'PATH'. -*lttng-list*(1):: - List possible tracing options +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`). -*lttng-set-session*(1):: - Set current session name -*lttng-snapshot*(1):: - Snapshot buffers of current session name +Program information +~~~~~~~~~~~~~~~~~~~ +option:-h, option:--help:: + Show help. -*lttng-start*(1):: - Start tracing +option:--list-commands:: + List available commands. -*lttng-stop*(1):: - Stop tracing +option:--list-options:: + List available general options. -*lttng-version*(1):: - Show version information +option:-V, option:--version:: + Show version. -*lttng-view*(1):: - Start trace viewer -*lttng-save*(1):: - Save session configuration +COMMANDS +-------- +The following commands also have their own option:--help option. -*lttng-load*(1):: - Load session configuration -*lttng-track*(1):: - Track specific system resources +Tracing sessions +~~~~~~~~~~~~~~~~ +linklttng:lttng-create(1):: + Create a tracing session. -*lttng-untrack*(1):: - Untrack specific system resources +linklttng:lttng-destroy(1):: + Tear down tracing sessions. -Each command also has its own -h, --help option. +linklttng:lttng-save(1):: + Save tracing session configurations. +linklttng:lttng-set-session(1):: + Set current tracing session. -EXIT STATUS ------------ -*0*:: - Success +linklttng:lttng-load(1):: + Load tracing session configurations. -*1*:: - Command error -*2*:: - Undefined command +Channels +~~~~~~~~ +linklttng:lttng-enable-channel(1):: + Create or enable tracing channels. -*3*:: - Fatal error +linklttng:lttng-disable-channel(1):: + Disable tracing channels. -*4*:: - Command warning (something went wrong during the command) +linklttng:lttng-add-context(1):: + Add context fields to a channel. -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. +Event rules +~~~~~~~~~~~ +linklttng:lttng-enable-event(1):: + Create or enable event rules. -ENVIRONMENT VARIABLES ---------------------- -Note that all command line options override environment variables. +linklttng:lttng-disable-event(1):: + Disable event rules. -*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. +Status +~~~~~~ +linklttng:lttng-list(1):: + List tracing sessions, domains, channels, and events. +linklttng:lttng-status(1):: + Get the status of the current tracing session. -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. +Control +~~~~~~~ +linklttng:lttng-snapshot(1):: + Snapshot buffers of current tracing session. -RESOURCES ---------- -A Web site is available at *http://lttng.org* for more information on the LTTng -project. +linklttng:lttng-start(1):: + Start tracing. -You can also find our git tree at *http://git.lttng.org*. +linklttng:lttng-stop(1):: + Stop tracing. -Mailing lists for support and development: *lttng-dev@lists.lttng.org*. -You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*. +Resource tracking +~~~~~~~~~~~~~~~~~ +linklttng:lttng-track(1):: + Track specific system resources. +linklttng:lttng-untrack(1):: + Untrack specific system resources. -COPYRIGHTS ----------- -lttng is distributed under the GNU General Public License version 2. See the -file *COPYING* for details. +Miscellaneous +~~~~~~~~~~~~~ +linklttng:lttng-calibrate(1):: + Quantify LTTng overhead. -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. +linklttng:lttng-help(1):: + Display help information about a command. -Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA -maintainer) and Jon Bernard for our Debian packages. +linklttng:lttng-version(1):: + Show version information. -Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de -Montreal for the LTTng journey. +linklttng:lttng-view(1):: + Start trace viewer. -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-cmd-footer.txt[] SEE ALSO -------- -*babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8), -*lttng-crash*(1) +linklttng:lttng-sessiond(8), +linklttng:lttng-relayd(8), +linklttng:lttng-crash(1), +linklttng:lttng-ust(3), +linklttng:babeltrace(1) -- 2.34.1