From ee717bf064ade68f47c763d60c2d534fd9fd0b96 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 4 Mar 2016 21:20:49 -0500 Subject: [PATCH 1/1] doc/man: convert lttng-sessiond(8) to AsciiDoc 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/Makefile.am | 4 +- doc/man/lttng-sessiond.8 | 251 ----------------------------- doc/man/lttng-sessiond.8.txt | 297 +++++++++++++++++++++++++++++++++++ 3 files changed, 299 insertions(+), 253 deletions(-) delete mode 100644 doc/man/lttng-sessiond.8 create mode 100644 doc/man/lttng-sessiond.8.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 8104a2e47..73e9e239b 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -31,10 +31,10 @@ MAN1_NAMES = \ lttng-enable-event \ lttng-disable-event MAN3_NAMES = -MAN8_NAMES = +MAN8_NAMES = lttng-sessiond MAN1_NO_ASCIIDOC_NAMES = lttng-crash MAN3_NO_ASCIIDOC_NAMES = -MAN8_NO_ASCIIDOC_NAMES = lttng-relayd lttng-sessiond +MAN8_NO_ASCIIDOC_NAMES = lttng-relayd # man pages destinations MAN1 = $(call manaddsuffix,.1,$(MAN1_NAMES)) diff --git a/doc/man/lttng-sessiond.8 b/doc/man/lttng-sessiond.8 deleted file mode 100644 index d3ab323d9..000000000 --- a/doc/man/lttng-sessiond.8 +++ /dev/null @@ -1,251 +0,0 @@ -.TH "LTTNG-SESSIOND" "8" "January 31, 2012" "" "" - -.SH "NAME" -lttng-sessiond \- LTTng 2.x 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 a viewer, like 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 used to trace her applications along side with a -root daemon or even a Bob daemon. We highly recommend 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 -them when the time has come. The user don't need to manage the lttng-consumerd. -.SH "OPTIONS" - -.PP -This program follows 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, \-\-version" -Show version. -.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 "-b, --background" -Start as a daemon, keeping console open -.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 SIGUSR1 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. When building a third party 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 " --agent-tcp-port" -Agent application registration TCP port (default: 5345) -.TP -.BR " --kmod-probes=probe1, probe2, ..." -Specify the kernel modules containing LTTng probes to load by the session daemon. -Only the component name of the probe needs to be specified, e.g. to load the -lttng-probe-irq and lttng-probe-sched use: --kmod-probes="irq, sched". -.TP -.BR " --extra-kmod-probes=probe1, probe2, ..." -Specify extra kernel modules containing LTTng probes to be loaded by the session -daemon. The list follows the format of the \fB--kmod-probes\fP option. -This list is appended to the list provided by \fB--kmod-probes\fP or, if -\fB--kmod-probes\fP is missing, to the default list of probes. -.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 -.TP -.BR "-l, --load PATH -Specify path from which to automatically load session configuration(s). -.TP -.BR "-f, --config PATH -Specify path from which to load daemon configuration. - -.SH "LOADING SESSIONS" - -.PP -By default, the session daemon tries to load session configuration(s) located -in the user default directory \fB~/.lttng/sessions/auto/\fP and in the system -wide one in \fB/etc/lttng/sessions/auto/\fP. Note that the directory containing -the session's configuration and lttng-sessiond MUST have the same UID for them -to be automatically loaded. - -Specifying a path with \-l, \-\-load PATH overrides the default directory and -UID check. The lttng-sessiond will simply check if it's accessible and try to -load every session file in it. -.PP - -.SH "ENVIRONMENT VARIABLES" - -.PP -Note that all command line options will override environment variables. -.PP - -.PP -.IP "LTTNG_CONSUMERD32_BIN" -Specify the 32-bit consumer binary path. \fB--consumerd32-path\fP -override this variable. -.IP "LTTNG_CONSUMERD64_BIN" -Specify the 64-bit consumer binary path. \fB--consumerd64-path\fP -override this variable. -.IP "LTTNG_CONSUMERD32_LIBDIR" -Specify the 64-bit library path containing libconsumer.so. -\fB--consumerd32-libdir\fP override this variable. -.IP "LTTNG_CONSUMERD64_LIBDIR" -Specify the 32-bit library path containing libconsumer.so. -\fB--consumerd64-libdir\fP override this variable. -.IP "LTTNG_DEBUG_NOCLONE" -Debug-mode disabling use of clone/fork. Insecure, but required to allow -debuggers to work with sessiond on some operating systems. -.IP "LTTNG_APP_SOCKET_TIMEOUT" -Control the timeout of application's socket when sending and receiving -commands. Takes an integer parameter: the timeout value, in seconds. -After this period of time, the application is unregistered by the -session daemon. A value of 0 or -1 means an infinite timeout. Default -value is 5 seconds. -.IP "LTTNG_NETWORK_SOCKET_TIMEOUT" -Control timeout of socket connection, receive and send. Takes an integer -parameter: the timeout value, in milliseconds. A value of 0 or -1 uses -the timeout of the operating system (this is the default). -.IP "LTTNG_SESSION_CONFIG_XSD_PATH" -Specify the path that contains the XML session configuration schema (xsd). -.IP "LTTNG_KMOD_PROBES" -Specify the kernel modules probes that should be loaded by the session daemon. -.IP "LTTNG_EXTRA_KMOD_PROBES" -Specify extra kernel modules probes that should be loaded by the session daemon. -.SH "SEE ALSO" - -.PP -babeltrace(1), lttng-ust(3), lttng(1) -.PP - -.SH "LIMITATIONS" - -.PP -For unprivileged user running lttng-sessiond, the maximum number of file -descriptors per process is usually 1024. This limits the number of traceable -applications since for each instrumented application there is two file -descriptors per-CPU and one more socket for bidirectional communication. - -For the root user, the limit is bumped to 65535. Future version will deal with -this limitation. -.PP - -.SH "BUGS" - -.PP -No show stopper bugs are known yet in this 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 General 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 detailed 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 Jérémie Galarneau . -.PP diff --git a/doc/man/lttng-sessiond.8.txt b/doc/man/lttng-sessiond.8.txt new file mode 100644 index 000000000..df119e78b --- /dev/null +++ b/doc/man/lttng-sessiond.8.txt @@ -0,0 +1,297 @@ +lttng-sessiond(8) +================= + + +NAME +---- +lttng-sessiond - LTTng 2 tracing session daemon + + +SYNOPSIS +-------- +[verse] +*lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent] + [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH'] + [option:--agent-tcp-port='PORT'] + [option:--apps-sock='PATH'] [option:--client-sock='PATH'] + [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...] + [option:--extra-kmod-probes='PROBE'[,'PROBE']...] + [option:--kconsumerd-err-sock='PATH'] + [option:--kconsumerd-cmd-sock='PATH']] + [option:--ustconsumerd32-err-sock='PATH'] + [option:--ustconsumerd64-err-sock='PATH'] + [option:--ustconsumerd32-cmd-sock='PATH'] + [option:--ustconsumerd64-cmd-sock='PATH'] + [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH'] + [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH'] + [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]] + + +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. + +LTTng consists of Linux kernel modules (for Linux kernel tracing) and +dynamically loaded libraries (for user application and library tracing). + +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 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. + +The LTTng session daemon manages trace data consumer daemons by spawning +them when necessary. You do not need to manage the consumer daemons +manually. + +NOTE: It is highly recommended to start the session daemon at boot time +for stable and long-term tracing. + + +Loading tracing session configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, the LTTng session daemon tries to load tracing session +configurations located in the user default directory +`$HOME/.lttng/sessions` and in the system one, `/etc/lttng/sessions`. +Note that both the directory containing the tracing session +configurations and the session daemon binary _must_ have the same UID +for the configurations to be automatically loaded. + +Specifying a path with the option:--load option overrides the default +directory _and_ the UID check. The session daemon simply checks if the +path is accessible and tries to load every tracing session configuration +in it. + + +OPTIONS +------- +Daemon configuration +~~~~~~~~~~~~~~~~~~~~ +option:-b, option:--background:: + Start as Unix daemon, but keep file descriptors (console) open. + Use the option:--daemonize option instead to close the file + descriptors. + +option:-d, option:--daemonize:: + Start as Unix daemon, and close file descriptors (console). Use the + option:--background option instead to keep the file descriptors + open. + +option:-f, option:--config='PATH':: + Load session daemon configuration from path 'PATH'. + +option:-g, option:--group='GROUP':: + Use 'GROUP' as Unix tracing group (default: `tracing`). + +option:-l, option:--load='PATH':: + Automatically load tracing session configurations from path 'PATH'. + +option:-S, option:--sig-parent:: + Send `SIGUSR1` to parent process to notify readiness. ++ +NOTE: This is used by linklttng:lttng(1) to get notified when the +session daemon is ready to accept commands. When building a third party +tool on liblttng-ctl, this option can be very handy to synchronize the +control tool and the session daemon. + + +Linux kernel tracing +~~~~~~~~~~~~~~~~~~~~ +option:--extra-kmod-probes='PROBE'[,'PROBE']...:: + Load specific LTTng Linux kernel modules when kernel tracing + is enabled (option:--no-kernel option is :not: specified), in + addition to loading the default list of LTTng kernel modules. ++ +Only the name of the probe needs to be specified, without the +`lttng-probe-` prefix and without the kernel module extension suffix. +For example, specify `sched` to load the `lttng-probe-sched.ko` kernel +module. + +option:--kmod-probes='PROBE'[,'PROBE']...:: + Only load specific LTTng Linux kernel modules when kernel tracing + is enabled (option:--no-kernel option is :not: specified). ++ +Only the name of the probe needs to be specified, without the +`lttng-probe-` prefix and without the kernel module extension suffix. +For example, specify `sched` to load the `lttng-probe-sched.ko` kernel +module. + +option:--no-kernel:: + Disable Linux kernel tracing. + + +Paths and ports +~~~~~~~~~~~~~~~ +option:--agent-tcp-port='PORT':: + Listen on TCP port 'PORT' for agent application registrations + (default: 5345). + +option:-a, option:--apps-sock='PATH':: + Set application Unix socket path to 'PATH'. + +option:-c, option:--client-sock='PATH':: + Set client Unix socket path to 'PATH'. + +option:--consumerd32-libdir='PATH':: + Set 32-bit consumer daemon library directory to 'PATH'. + +option:--consumerd32-path='PATH':: + Set 32-bit consumer daemon binary path to 'PATH'. + +option:--consumerd64-libdir='PATH':: + Set 64-bit consumer daemon library directory to 'PATH'. + +option:--consumerd64-path='PATH':: + Set 64-bit consumer daemon binary path to 'PATH'. + +option:--kconsumerd-cmd-sock='PATH':: + Set Linux kernel consumer daemon's command Unix socket path + to 'PATH'. + +option:--kconsumerd-err-sock='PATH':: + Set Linux kernel consumer daemon's error Unix socket path + to 'PATH'. + +option:--ustconsumerd32-cmd-sock='PATH':: + Set 32-bit consumer daemon's command Unix socket path to 'PATH'. + +option:--ustconsumerd64-cmd-sock='PATH':: + Set 64-bit consumer daemon's command Unix socket path to 'PATH'. + +option:--ustconsumerd32-err-sock='PATH':: + Set 32-bit consumer daemon's error Unix socket path to 'PATH'. + +option:--ustconsumerd64-err-sock='PATH':: + Set 64-bit consumer daemon's error Unix socket path to 'PATH'. + + +Verbosity +~~~~~~~~~ +option:-q, option:--quiet:: + Suppress all messages, including warnings and errors. + +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`). + +option:--verbose-consumer:: + Increase verbosity of consumer daemons spawned by this session + daemon. + + +Program information +~~~~~~~~~~~~~~~~~~~ +option:-h, option:--help:: + Show help. + +option:-V, option:--version:: + Show version. + + +ENVIRONMENT VARIABLES +--------------------- +Note that command-line options override their equivalent environment +variable. + +`LTTNG_APP_SOCKET_TIMEOUT`:: + Application socket's timeout (seconds) when sending/receiving + commands. After this period of time, the application is unregistered + by the session daemon. A value of 0 or -1 means an infinite timeout. + Default value: 5. + +`LTTNG_CONSUMERD32_BIN`:: + 32-bit consumer daemon binary path. ++ +The option:--consumerd32-path option overrides this variable. + +`LTTNG_CONSUMERD32_LIBDIR`:: + 32-bit consumer daemon library path. ++ +The option:--consumerd32-libdir option overrides this variable. + +`LTTNG_CONSUMERD64_BIN`:: + 64-bit consumer daemon binary path. ++ +The option:--consumerd64-path option overrides this variable. + +`LTTNG_CONSUMERD64_LIBDIR`:: + 64-bit consumer daemon library path. ++ +The option:--consumerd64-libdir option overrides this variable. + +`LTTNG_DEBUG_NOCLONE`:: + Set to 1 to disable the use of `clone()`/`fork()`. Setting this + variable is considered insecure, but it is required to allow + debuggers to work with the session daemon on some operating systems. + +`LTTNG_EXTRA_KMOD_PROBES`:: + Load specific LTTng Linux kernel modules when kernel tracing + is enabled (option:--no-kernel option is :not: specified), in + addition to loading the default list of LTTng kernel modules. ++ +The option:--extra-kmod-probes option overrides this variable. + +`LTTNG_KMOD_PROBES`:: + Only load specific LTTng Linux kernel modules when kernel tracing + is enabled (option:--no-kernel option is :not: specified). ++ +The option:--kmod-probes option overrides this variable. + +`LTTNG_NETWORK_SOCKET_TIMEOUT`:: + Socket connection, receive and send timeout (milliseconds). A value + of 0 or -1 uses the timeout of the operating system (default). + +`LTTNG_SESSION_CONFIG_XSD_PATH`:: + Tracing session configuration XML schema definition (XSD) path. + + +EXIT STATUS +----------- +*0*:: + Success + +*1*:: + Error + +*3*:: + Fatal error + + +LIMITATIONS +----------- +For an unprivileged user running `lttng-sessiond`, the maximum number of +file descriptors per process is usually 1024. This limits the number of +traceable applications, since for each instrumented application, there +is two file descriptors per CPU and one more socket for bidirectional +communication. + +For the root user, the limit is bumped to 65535. A future version will +deal with this limitation. + + +include::common-footer.txt[] + + +SEE ALSO +-------- +linklttng:lttng(1), +linklttng:lttng-relayd(8), +linklttng:lttng-crash(1), +linklttng:lttng-ust(3), +linklttng:babeltrace(1) -- 2.34.1