From 6991b1817066a4a0a618f85adfdfb9aa8f2bd524 Mon Sep 17 00:00:00 2001 From: David Goulet Date: Tue, 24 Jan 2012 17:29:14 -0500 Subject: [PATCH] Initial import of man lttng.1 and lttng-sessiond.8 This is the first import and first draft of lttng-tools man pages. It is most likely that they still contain a lot of mistakes. Signed-off-by: David Goulet --- configure.ac | 1 + doc/Makefile.am | 3 +- doc/man/Makefile.am | 3 + doc/man/lttng-sessiond.8 | 178 ++++++++++++ doc/man/lttng.1 | 585 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 769 insertions(+), 1 deletion(-) create mode 100644 doc/man/Makefile.am create mode 100644 doc/man/lttng-sessiond.8 create mode 100644 doc/man/lttng.1 diff --git a/configure.ac b/configure.ac index f9a16664e..ffd54e2e6 100644 --- a/configure.ac +++ b/configure.ac @@ -150,6 +150,7 @@ AC_SUBST(DEFAULT_INCLUDES) AC_CONFIG_FILES([ Makefile doc/Makefile + doc/man/Makefile include/Makefile src/Makefile src/common/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index ac359426f..8838d0309 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1,4 @@ -EXTRA_DIST = session-daemon-model.txt +SUBDIR = man +EXTRA_DIST = quickstart.txt session-daemon-model.txt dist_doc_DATA = quickstart.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 000000000..bdf0394f0 --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,3 @@ +EXTRA_DIST = lttng.1 lttng-sessiond.8 +dist_man1_MANS = lttng.1 +dist_man8_MANS = lttng-sessiond.8 diff --git a/doc/man/lttng-sessiond.8 b/doc/man/lttng-sessiond.8 new file mode 100644 index 000000000..d71abb349 --- /dev/null +++ b/doc/man/lttng-sessiond.8 @@ -0,0 +1,178 @@ +.TH "LTTNG-SESSIOND" "8" "January 31, 2012" "" "" + +.SH "NAME" +lttng-sessiond \(em LTTng 2.0 central tracing registry session daemon. + +.SH "SYNOPSIS" + +.PP +.nf +lttng-sessiond [OPTIONS] +.fi +.SH "DESCRIPTION" + +.PP +The LTTng project aims at providing highly efficient tracing tools for Linux. +It's tracers help tracking down performance issues and debugging problems +involving multiple concurrent processes and threads. Tracing across multiple +systems is also possible. + +The session daemon, acting as a tracing registry, allow you to interact with +multiple tracers (kernel and user-space) inside the same container, a tracing +session. Trace can be gathered from the kernel and/or instrumented applications +(lttng-ust(3)). Aggregating those traces is done using the babeltrace(1) text +viewer. + +In order to trace the kernel, the session daemon needs to be running as root. +LTTng provides the use of a \fBtracing group\fP (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 use to trace her applications along side with a +root daemon or even a Bob daemon. We highly recommand to start the session +daemon at boot time for stable and long term tracing. + +The session daemon is in charge of managing trace data consumers by spawning +one when the time as come. The user don't need to manage the lttng-consumerd. +.SH "OPTIONS" + +.PP +This program follow the usual GNU command line syntax with long options starting with +two dashes. Below is a summary of the available options. +.PP + +.TP +.BR "-h, --help" +Show summary of possible options and commands +.TP +.BR "-v, --verbose" +Increase verbosity + +There is three debugging level which will print on stderr. Maximum verbosity is +\fB-vvv\fP. +.TP +.BR " --verbose-consumer" +Verbose mode for consumer. Activate DBG() macro. +.TP +.BR "-d, --daemonize" +Start as a daemon +.TP +.BR "-g, --group=NAME" +Specify the tracing group name. (default: tracing) +.TP +.BR "-V, --version" +Show version number +.TP +.BR "-S, --sig-parent" +Send SIGCHLD to parent pid to notify readiness. + +This is used by \fBlttng(1)\fP to get notified when the session daemon is ready +to accept command. By building a third part tool over liblttng-ctl, this option +can be very handy to synchronize the control tool and the session daemon. +.TP +.BR "-q, --quiet" +No output at all. +.TP +.BR " --no-kernel" +No kernel tracer support +.TP +.BR "-c, --client-sock=PATH" +Specify path for the client unix socket +.TP +.BR "-a, --apps-sock PATH" +Specify path for apps unix socket +.TP +.BR " --kconsumerd-err-sock=PATH" +Specify path for the kernel consumer error socket +.TP +.BR " --kconsumerd-cmd-sock=PATH +Specify path for the kernel consumer command socket +.TP +.BR " --ustconsumerd32-err-sock=PATH +Specify path for the 32-bit UST consumer error socket +.TP +.BR " --ustconsumerd64-err-sock=PATH +Specify path for the 64-bit UST consumer error socket +.TP +.BR " --ustconsumerd32-cmd-sock=PATH +Specify path for the 32-bit UST consumer command socket +.TP +.BR " --ustconsumerd64-cmd-sock=PATH +Specify path for the 64-bit UST consumer command socket +.TP +.BR " --consumerd32-path=PATH +Specify path for the 32-bit UST consumer daemon binary +.TP +.BR " --consumerd32-libdir=PATH +Specify path for the 32-bit UST consumer daemon libraries +.TP +.BR " --consumerd64-path=PATH +Specify path for the 64-bit UST consumer daemon binary +.TP +.BR " --consumerd64-libdir=PATH +Specify path for the 64-bit UST consumer daemon libraries +.SH "ENVIRONMENT VARIABLES" + +.PP +Note that all command line options will override environmenal variables. +.PP + +.PP +.IP "LTTNG_CONSUMERD32_BIN" +Allow to specify the 32-bit consumer binary path. \fB--consumerd32-path\fP +override this variable. +.IP "LTTNG_CONSUMERD64_BIN" +Allow to specify the 64-bit consumer binary path. \fB--consumerd64-path\fP +override this variable. +.IP "LTTNG_CONSUMERD32_LIBDIR" +Allow to specifiy the 64-bit library path containing libconsumer.so. +\fB--consumerd32-libdir\fP override this variable. +.IP "LTTNG_CONSUMERD64_LIBDIR" +Allow to specifiy the 32-bit library path containing libconsumer.so. +\fB--consumerd64-libdir\fP override this variable. +.SH "SEE ALSO" + +.PP +babeltrace(1), lttng-ust(3), lttng(1) +.PP +.SH "BUGS" + +.PP +No show stopper bugs known yet at this stable version. + +If you encounter any issues or usability problem, please report it on our +mailing list to help improve this project. +.SH "CREDITS" + +.PP +lttng-sessiond is distributed under the GNU public license version 2. See the +file COPYING for details. +.PP +A Web site is available at http://lttng.org for more information on the LTTng +project. +.PP +You can also find our git tree at http://git.lttng.org. +.PP +Mailing lists for support and development: . +.PP +You can find us on IRC server irc.oftc.net (OFTC) in #lttng. +.PP +.SH "THANKS" + +.PP +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 help +us greatly with detailled bug reports and unsual use cases. + +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. +.pp +.SH "AUTHORS" + +.PP +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 David Goulet . +.PP diff --git a/doc/man/lttng.1 b/doc/man/lttng.1 new file mode 100644 index 000000000..31fcbcc03 --- /dev/null +++ b/doc/man/lttng.1 @@ -0,0 +1,585 @@ +.TH "LTTNG" "1" "February 9, 2012" "" "" + +.SH "NAME" +lttng \(em LTTng 2.0 tracer control command line tool + +.SH "SYNOPSIS" + +.PP +.nf +lttng [OPTIONS] +.fi +.SH "DESCRIPTION" + +.PP +The LTTng project aims at providing highly efficient tracing tools for Linux. +It's tracers help tracking down performance issues and debugging problems +involving multiple concurrent processes and threads. Tracing across multiple +systems is also possible. + +The \fBlttng\fP command line tool from lttng-tools package is used to control +both kernel and user-space tracing. Every interactions with the tracer should +be done by this tool or by the liblttng-ctl provided with the lttng-tools +package. + +LTTng uses a session daemon (lttng-sessiond(8)), acting as a tracing registry, +which permits 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. + +In order to trace the kernel, the session daemon needs to be running as root. +LTTng provides the use of a \fBtracing group\fP (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 use to trace her applications along side with a +root daemon or even a Bob daemon. We highly recommand to start the session +daemon at boot time for stable and long term tracing. + +Every user-space applications instrumented with lttng-ust(3), will +automatically register to the session daemon. This feature gives you the +ability to list available traceable applications and tracepoints on a per user +basis. (See \fBlist\fP command). +.SH "OPTIONS" + +.PP +This program follow the usual GNU command line syntax with long options starting with +two dashes. Below is a summary of the available options. +.PP + +.TP +.BR "-h, --help" +Show summary of possible options and commands. +.TP +.BR "-v, --verbose" +Increase verbosity. +FIXME : details (-v : sessiond verbose, -vv : consumerd verbose, etc) ? +.TP +.BR "-q, --quiet" +Suppress all messages (even errors). +.TP +.BR "-g, --group NAME" +Set unix tracing group name. (default: tracing) +.TP +.BR "-n, --no-sessiond" +Don't automatically spawn a session daemon. +.TP +.BR "--sessiond-path" +Set session daemon full binary path. +.TP +.BR "--list-options" +Simple listing of lttng options. +.TP +.BR "--list-commands" +Simple listing of lttng commands. +.SH "COMMANDS" + +.TP +\fBadd-context\fP +.nf +Add context to event(s) and/or channel(s). + +A context is basically extra information appended to a channel or event. For +instance, you could ask the tracer to add the PID information within the +"sched_switch" kernel event. You can also add performance monitoring unit +counters (perf PMU) using the perf kernel API). + +For example, this command will add the context information 'prio' and two perf +counters (hardware branch misses and cache misses), to all events in the trace +data output: + +# lttng add-context -k -t prio -t perf:branch-misses -t perf:cache-misses + +Please take a look at the help (-h/--help) for a detailed list of available +contexts. + +If no channel and no event is given (-c/-e), the context is added to all +channels (which applies automatically to all events in that channel). Otherwise +the context will be added only to the channel (-c) and/or event (-e) indicated. + +If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +-s, --session NAME + Apply on session name. +-c, --channel NAME + Apply on channel name. +-e, --event NAME + Apply on event name. +-k, --kernel + Apply for the kernel tracer +-u, --userspace + Apply for the user-space tracer +-t, --type TYPE + Context type. You can repeat this option on the command line. Please + use "lttng add-context -h" to list all available types. +.fi + +.IP + +.IP "\fBcalibrate\fP" +.nf +Quantify LTTng overhead + +The LTTng calibrate command can be used to find out the combined average +overhead of the LTTng tracer and the instrumentation mechanisms used. This +overhead can be calibrated in terms of time or using any of the PMU performance +counter available on the system. + +For now, the only calibration implemented is that of the kernel function +instrumentation (kretprobes). + +* Calibrate kernel function instrumentation + +Let's use an example to show this calibration. We use an i7 processor with 4 +general-purpose PMU registers. This information is available by issuing dmesg, +looking for "generic registers". + +This sequence of commands will gather a trace executing a kretprobe hooked on +an empty function, gathering PMU counters LLC (Last Level Cache) misses +information (see lttng add-context --help to see the list of available PMU +counters). + +# lttng create calibrate-function +# lttng enable-event calibrate --kernel --function lttng_calibrate_kretprobe +# lttng add-context --kernel -t perf:LLC-load-misses -t perf:LLC-store-misses \\ + -t perf:LLC-prefetch-misses +# lttng start +# for a in $(seq 1 10); do \\ + lttng calibrate --kernel --function; + done +# lttng destroy +# babeltrace $(ls -1drt ~/lttng-traces/calibrate-function-* | tail -n 1) + +The output from babeltrace can be saved to a text file and opened in a +spreadsheet (e.g. oocalc) to focus on the per-PMU counter delta between +consecutive "calibrate_entry" and "calibrate_return" events. Note that these +counters are per-CPU, so scheduling events would need to be present to account +for migration between CPU. Therefore, for calibration purposes, only events +staying on the same CPU must be considered. + +The average result, for the i7, on 10 samples: + + Average Std.Dev. +perf_LLC_load_misses: 5.0 0.577 +perf_LLC_store_misses: 1.6 0.516 +perf_LLC_prefetch_misses: 9.0 14.742 + +As we can notice, the load and store misses are relatively stable across runs +(their standard deviation is relatively low) compared to the prefetch misses. +We can conclude from this information that LLC load and store misses can be +accounted for quite precisely, but prefetches within a function seems to behave +too erratically (not much causality link between the code executed and the CPU +prefetch activity) to be accounted for. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +-k, --kernel + Apply for the kernel tracer +-u, --userspace + Apply for the user-space tracer +--function + Dynamic function entry/return probe (default) +.fi + +.IP + +.IP "\fBcreate\fP [OPTIONS] [NAME] +.nf +Create tracing session. + +A tracing session contains channel(s) which contains event(s). It is domain +agnostic meaning that you can enable channels and events for either the +user-space tracer and/or the kernel tracer. It acts like a container +aggregating multiple tracing sources. + +On creation, a \fB.lttngrc\fP file is created in your $HOME directory +containing the current session name. If NAME is omitted, a session name is +automatically created having this form: 'auto-yyyymmdd-hhmms'. + +If no \fB-o, --output\fP is specified, the traces will be written in +$HOME/lttng-traces. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +-o, --output PATH + Specify output path for traces +.fi + +.IP + +.IP "\fBdestroy\fP [OPTIONS] [NAME]" +.nf +Teardown tracing session + +Free memory on the session daemon and tracer side. It's gone! + +If NAME is omitted, the session name is taken from the .lttngrc file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +.fi + +.IP + +.IP "\fBenable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" +.nf +Enable tracing channel + +If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show this help +--list-options + Simple listing of options +-s, --session + Apply on session name +-k, --kernel + Apply to the kernel tracer +-u, --userspace + Apply to the user-space tracer + +--discard + Discard event when subbuffers are full (default) +--overwrite + Flight recorder mode : overwrites events when subbuffers are full +--subbuf-size + Subbuffer size in bytes (default: 4096, kernel default: 262144) +--num-subbuf + Number of subbufers (default: 8, kernel default: 4) +--switch-timer + Switch subbuffer timer interval in usec (default: 0) +--read-timer + Read timer interval in usec (default: 200) +.fi + +.IP + +.IP "\fBenable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" +.nf +Enable tracing event + +A tracing event is always assigned to a channel. If \fB-c, --channel\fP is +omitted, a default channel named '\fBchannel0\fP' is created and the event is +added to it. For the user-space tracer, using \fB-a, --all\fP is the same as +using the wildcard "*". + +If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +-s, --session + Apply on session name +-c, --channel + Apply on channel name +-a, --all + Enable all tracepoints +-k, --kernel + Apply for the kernel tracer +-u, --userspace + Apply for the user-space tracer + +--tracepoint + Tracepoint event (default) + - userspace tracer supports wildcards at end of string. Don't forget to + quote to deal with bash expansion. + e.g.: + "*" + "app_component:na*" +--loglevel + Tracepoint loglevel +--probe [addr | symbol | symbol+offset] + Dynamic probe. Addr and offset can be octal (0NNN...), decimal (NNN...) + or hexadecimal (0xNNN...) +--function [addr | symbol | symbol+offset] + Dynamic function entry/return probe. Addr and offset can be octal + (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...) +--syscall + System call event + Enabling syscalls tracing (kernel tracer), you will not be able to disable them + with disable-event. This is a known limitation. You can disable the entire + channel to do the trick. +.fi + +.IP "\fBdisable-channel\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" +.nf +Disable tracing channel + +Disabling a channel makes all event(s) in that channel to stop tracing. You can +enable it back by calling \fBlttng enable-channel NAME\fP again. + +If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +-s, --session + Apply on session name +-k, --kernel + Apply for the kernel tracer +-u, --userspace + Apply for the user-space tracer +.fi + +.IP "\fBdisable-event\fP NAME[,NAME2,...] [-k|-u] [OPTIONS]" +.nf +Disable tracing event + +The event, once disabled, can be re-enabled by calling \fBlttng enable-event +NAME\fP again. + +If \fB-s, --session\fP is omitted, the session name is taken from the .lttngrc +file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +-s, --session + Apply on session name +-k, --kernel + Apply for the kernel tracer +-u, --userspace + Apply for the user-space tracer +.fi + +.IP "\fBlist\fP [-k|-u] [SESSION [SESSION_OPTIONS]]" +.nf +List tracing session informations. + +With no arguments, it will list available tracing session(s). + +With -k alone, it will list all available kernel events (except the system +calls events). +With -u alone, it will list all available user-space events from registered +applications. Here is an example of 'lttng list -u': + +PID: 7448 - Name: /tmp/lttng-ust/tests/hello/.libs/lt-hello + ust_tests_hello:tptest_sighandler (type: tracepoint) + ust_tests_hello:tptest (type: tracepoint) + +You can now enable any event listed by using the name : +\fBust_tests_hello:tptest\fP. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +-k, --kernel + Select kernel domain (FIXME : apparition de la notion de "domain" ici) +-u, --userspace + Select user-space domain. + +Session options: +-c, --channel NAME + List details of a channel +-d, --domain + List available domain(s) +.fi + +.IP "\fBset-session\fP NAME" +.nf +Set current session name + +Will change the session name in the .lttngrc file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +.fi + +.IP + +.IP "\fBstart\fP [OPTIONS] [NAME]" +.nf +Start tracing + +It will start tracing for all tracers for a specific tracing session. + +If NAME is omitted, the session name is taken from the .lttngrc file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +.fi + +.IP + +.IP "\fBstop\fP [OPTIONS] [NAME]" +.nf +Stop tracing + +It will stop tracing for all tracers for a specific tracing session. + +If NAME is omitted, the session name is taken from the .lttngrc file. +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +.fi + +.IP + +.IP "\fBversion\fP" +.nf +Show version information +.fi + +.B OPTIONS: + +.nf +-h, --help + Show summary of possible options and commands. +--list-options + Simple listing of options +.fi + +.IP + +.IP "\fBview\fP [SESSION_NAME] [OPTIONS]" +.nf +View traces of a tracing session + +By default, the babeltrace viewer will be used for text viewing. + +The SESSION_NAME is an optional session name. If not specified, lttng will get +it from the configuration file (.lttngrc). +.fi + +.B OPTIONS: + +.nf +-h, --help + Show this help +--list-options + Simple listing of options +-t, --trace-path PATH + Trace directory path for the viewer +-e, --viewer CMD + Specify viewer and/or options to use + This will completely override the default viewers so + please make sure to specify the full command. The trace + directory path of the session will be appended at the end + to the arguments +.fi + +.SH "ENVIRONMENT VARIABLES" + +.PP +Note that all command line options override environment variables. +.PP + +.PP +.IP "LTTNG_SESSIOND_PATH_ENV" +Allows to specify the full session daemon binary path to lttng command line +tool. You can also use --sessiond-path option having the same effect. +.SH "SEE ALSO" + +.PP +babeltrace(1), lttng-ust(3), lttng-sessiond(8) +.PP +.SH "BUGS" + +.PP +No show stopper bugs known yet at this stable version. + +If you encounter any issues or usability problem, please report it on our +mailing list to help improve this project. +.SH "CREDITS" + +.PP +lttng is distributed under the GNU public license version 2. See the file +COPYING for details. +.PP +A Web site is available at http://lttng.org for more information on the LTTng +project. +.PP +You can also find our git tree at http://git.lttng.org. +.PP +Mailing lists for support and development: . +.PP +You can find us on IRC server irc.oftc.net (OFTC) in #lttng. +.PP +.SH "THANKS" + +.PP +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 detailled bug reports and unusual test cases. + +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. +.pp +.SH "AUTHORS" + +.PP +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 David Goulet . +.PP -- 2.34.1