From: Philippe Proulx Date: Mon, 7 Mar 2016 06:35:18 +0000 (-0500) Subject: doc/man: convert lttng-relayd(8) to AsciiDoc X-Git-Tag: v2.8.0-rc1~18 X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=f5595c32860c47824e35760dda5d3680425adddf doc/man: convert lttng-relayd(8) to AsciiDoc Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 98d37caa3..cbafbce94 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -32,10 +32,10 @@ MAN1_NAMES = \ lttng-disable-event \ lttng-crash MAN3_NAMES = -MAN8_NAMES = lttng-sessiond +MAN8_NAMES = lttng-sessiond lttng-relayd MAN1_NO_ASCIIDOC_NAMES = MAN3_NO_ASCIIDOC_NAMES = -MAN8_NO_ASCIIDOC_NAMES = lttng-relayd +MAN8_NO_ASCIIDOC_NAMES = # man pages destinations MAN1 = $(call manaddsuffix,.1,$(MAN1_NAMES)) diff --git a/doc/man/lttng-relayd.8 b/doc/man/lttng-relayd.8 deleted file mode 100644 index fcde15ef1..000000000 --- a/doc/man/lttng-relayd.8 +++ /dev/null @@ -1,139 +0,0 @@ -.TH "LTTNG-RELAYD" "8" "July 15, 2012" "" "" - -.SH "NAME" -lttng-relayd \- LTTng remote trace collection daemon - -.SH "SYNOPSIS" - -.PP -.nf -lttng-relayd [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 relay daemon listens by default on all network interfaces to gather -trace data, but only on localhost for viewer connections. This daemon -does not require any particular permissions as long as it can write in -the output folder and listen on the ports. If a user is within a secured -network and/or has proper firewall settings, lttng-relayd can listen to -viewer connections from all network interfaces by specifying '-L -tcp://0.0.0.0:5344'. - -Traces can be either viewed "live" (as they are produced) by attaching -to the live viewer port using LTTng live protocol, or after tracing has -been stopped. Once a trace has been streamed completely, the trace can -be processed by any tool that can process a local LTTng CTF trace. - -By default, the relayd outputs the traces in : -~/lttng-traces/hostname/session-name/domain-name - -The prefix (~/lttng-traces) can be configured on the relayd side (see below for -the option), the other folders can be configured when creating the trace on the -sessiond side. -.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 "-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 "-C, --control-port" -Control port URL (tcp://0.0.0.0:5342 is the default) -.TP -.BR "-D, --data-port" -Data port URL (tcp://0.0.0.0:5343 is the default) -.TP -.BR "-L, --live-port URL" -Live view port URL (tcp://localhost:5344 is the default). -.TP -.BR "-o, --output" -Output base directory. Must use an absolute path (~/lttng-traces is the default) -.TP -.BR "-V, --version" -Show version number -.SH "ENVIRONMENT VARIABLES" - -.PP -.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_RELAYD_HEALTH" -File path used for relay daemon health check communication. -.PP - -.SH "SEE ALSO" - -.PP -babeltrace(1), lttng-sessiond(8), lttng-ust(3), lttng(1) -.PP - -.SH "LIMITATIONS" - -.PP -For now only TCP is supported on both control and data port. -Control will always remain TCP-only since it is low-volume and needs absolutely -to be reliable, but eventually the data connection could support UDP. - -For unprivileged user running lttng-relayd, the maximum number of file -descriptors per process is usually 1024. This limits the number of connections -and tracefiles opened. This limit can be configured see ulimit(3). -.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-relayd 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 "AUTHORS" - -.PP -lttng-relay was originally written by Julien Desfossez and -David Goulet. More people have since contributed to it. It is currently -maintained by Julien Desfossez . -.PP diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt new file mode 100644 index 000000000..32eccbeda --- /dev/null +++ b/doc/man/lttng-relayd.8.txt @@ -0,0 +1,193 @@ +lttng-relayd(8) +=============== + + +NAME +---- +lttng-relayd - LTTng 2 relay daemon + + +SYNOPSIS +-------- +[verse] +*lttng-relayd* [option:--background | option:--daemonize] + [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL'] + [option:--output='PATH'] [option:-v | option:-vv | option:-vvv] + + +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 relay daemon_ is responsible for receiving trace data from +possibly remote LTTng session/consumer daemons and for writing it to +the local file system. The relay daemon also accepts _LTTng live_ +connections from compatible viewers; this is the official approach to +viewing LTTng events as they are emitted. + +The relay daemon listens by default on all network interfaces to gather +trace data, but only on localhost for LTTng live connections. + +The relay daemon does not require any particular permissions, as long as +it can write to the output directory and listen on the configured ports. +If a user is within a secured network and/or has proper firewall +settings, `lttng-relayd` can listen to LTTng live connections from _all_ +network interfaces by specifying `--live-port=tcp://0.0.0.0:5344`. + +Once a trace has been streamed completely, the trace can be processed by +any tool that can process an LTTng trace located on the local +file system. + + +[[output-directory]] +Output directory +~~~~~~~~~~~~~~~~ +By default, the relay daemon writes the traces to: + +[verse] +$HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN' + +with: + +'HOSTNAME':: + Remote hostname. + +'SESSION':: + Full session name. + +'DOMAIN':: + Tracing domain. + +You can override the default output directory prefix +(`$HOME/lttng-traces`) with the option:--output option. The other +parts depend on the remote configuration. + + +[[url-format]] +URL format +~~~~~~~~~~ +The option:--control-port, option:--data-port, and option:--live-port +options specify URLs. + +The format of those URLs is: + +[verse] +tcp://('HOST' | 'IPADDR'):__PORT__ + +with: + +('HOST' | 'IPADDR'):: + Binding hostname or IP address (IPv6 address *must* be enclosed in + brackets (`[` and `]`); see + https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). + +'PORT':: + TCP port. + + +OPTIONS +------- +Daemon +~~~~~~ +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:-g, option:--group='GROUP':: + Use 'GROUP' as Unix tracing group (default: `tracing`). + +option:-o, option:--output='PATH':: + Set base directory of written trace data to 'PATH'. ++ +See the <> section above for more +information. + +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`). + + +Ports +~~~~~ +See the <> section above for more information +about the syntax of the following options' 'URL' argument. + +option:-C, option:--control-port='URL':: + Listen to control data on URL 'URL' (default: `tcp://0.0.0.0:5342`). + +option:-D, option:--data-port='URL':: + Listen to trace data on URL 'URL' (default: `tcp://0.0.0.0:5343`). + +option:-L, option:--live-port='URL':: + Listen to LTTng live connections on URL 'URL' + (default: `tcp://0.0.0.0:5344`). + + +Program information +~~~~~~~~~~~~~~~~~~~ +option:-h, option:--help:: + Show help. + +option:-V, option:--version:: + Show version. + + +ENVIRONMENT VARIABLES +--------------------- +`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_RELAYD_HEALTH`:: + Path to relay daemon health's socket. + + +EXIT STATUS +----------- +*0*:: + Success + +*1*:: + Error + +*3*:: + Fatal error + + +LIMITATIONS +----------- +As of this version, only the TCP protocol is supported for both control +and data ports. In future versions, TCP will remain the sole available +protocol for control data since those communications are low-volume and +need absolute reliability; trace data could be carried over UDP. + +For an unprivileged user running `lttng-relayd`, the maximum number of +file descriptors per process is usually 1024. This limits the number of +connections and opened trace files. This limit can be configured with +*ulimit*(3). + + +include::common-footer.txt[] + + +SEE ALSO +-------- +linklttng:lttng(1), +linklttng:lttng-sessiond(8), +linklttng:lttng-crash(1), +linklttng:lttng-ust(3), +linklttng:babeltrace(1)