From: Philippe Proulx Date: Thu, 2 Apr 2020 19:32:59 +0000 (-0400) Subject: lttng-relayd(8): normalize style and add details X-Git-Tag: v2.13.0-rc1~685 X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=commitdiff_plain;h=fd00593c84e51522e11a9c637a77b5f01c52d70d lttng-relayd(8): normalize style and add details Signed-off-by: Philippe Proulx Change-Id: Ifd2e90686bf9955f0c68fe158c60344d346814d0 Signed-off-by: Jérémie Galarneau --- diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt index f5a5bcd10..99d5b07ed 100644 --- a/doc/man/lttng-relayd.8.txt +++ b/doc/man/lttng-relayd.8.txt @@ -1,6 +1,6 @@ lttng-relayd(8) =============== -:revdate: 5 June 2018 +:revdate: 2 April 2020 NAME @@ -15,7 +15,8 @@ SYNOPSIS [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT'] [option:--live-port='URL'] [option:--output='PATH'] [option:-v | option:-vv | option:-vvv] [option:--working-directory='PATH'] - [option:--group-output-by-session | option:--group-output-by-host] + [option:--group-output-by-session] [option:--disallow-clear] + DESCRIPTION ----------- @@ -50,40 +51,84 @@ file system. [[output-directory]] Output directory ~~~~~~~~~~~~~~~~ -By default (option:--group-output-by-host), the relay daemon writes the traces -to: +The relay daemon uses different output path patterns depending on: -[verse] -$LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN' +* Its configuration. +* The connected peer's tracing session configuration. +* The connected peer's LTTng session daemon (see man:lttng-sessiond(8)) + version. -with: +Consider the following variables: + +'BASE':: + Base output directory: `$LTTNG_HOME/lttng-traces` or the + argument of the option:--output option. ++ +NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. 'HOSTNAME':: - Remote hostname. + Peer's hostname. 'SESSION':: - Full session name. + Tracing session name. + +'DATETIME':: + Unique tracing session date/time. -'DOMAIN':: - Tracing domain. +'TRACEPATH':: + Custom trace path ('TRACEPATH' part of the man:lttng-create(1) + command's nloption:--set-url option's argument, if any). -You can group the output per session instead of per hostname with the -option:--group-output-by-session option. This result in the following: +The relay daemon output path patterns are: + +Hostname grouping (without option:--group-output-by-session):: + Without a custom trace path::: ++ +-- +[verse] +'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' +-- + +With a custom trace path::: ++ +-- +[verse] +'BASE'/'HOSTNAME'/'TRACEPATH' +-- +Tracing session grouping (with option:--group-output-by-session):: + Without a custom trace path::: + The peer's LTTng session daemon version is at least 2.4:::: ++ +-- [verse] +'BASE'/'SESSION'/'HOSTNAME'-'DATETIME' +-- -$LTTNG_HOME/lttng-traces/'SESSION'/'HOST'/'DOMAIN' +Otherwise:::: + Defaults to the hostname grouping pattern: ++ +-- +[verse] +'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' +-- -You can override the default output directory prefix -(`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other -parts depend on the remote configuration. +With a custom trace path::: + The peer's LTTng session daemon version is at least 2.4:::: ++ +-- +[verse] +'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEPATH' +-- -Grouping by session is not supported for peers with version inferior to 2.4. -In such cases, the grouping of output for that particular peer will be per host -(default). +Otherwise:::: + Defaults to the hostname grouping pattern: ++ +-- +[verse] +'BASE'/'HOSTNAME'/'TRACEPATH' +-- -A best effort backward compatibility is done for peers version greater or equal to -2.4 and smaller than 2.11. [[url-format]] URL format @@ -121,35 +166,28 @@ option:-d, option:--daemonize:: option:--background option instead to keep the file descriptors open. -option:--fd-pool-size='SIZE':: - Set the size of the file descriptor pool. This effectively sets a - limit on the number of file descriptors that may be kept open - simultaneously by the daemon (default: the soft `RLIMIT_NOFILE` resource - limit of the process). - -option:-g 'GROUP', option:--group='GROUP':: - Use 'GROUP' as Unix tracing group (default: `tracing`). - -option:-o 'PATH', option:--output='PATH':: - Set base directory of written trace data to 'PATH'. +option:-x, option:--disallow-clear:: + Disallow clearing operations (see man:lttng-clear(1)). + -See the <> section above for more -information. +See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable. -option:-p, option:--group-output-by-host:: - Organize the output directory by host. Default behavior. +option:--fd-pool-size='SIZE':: + Set the size of the file descriptor pool to 'SIZE'. + -See the <> section above for more -information. - -option:-s, option:--group-output-by-session:: - Organize the output directory by session. +'SIZE' is the maximum number of file descriptors that may be kept opened +simultaneously by the relay daemon. + -See the <> section above for more -information. +Default: the soft `RLIMIT_NOFILE` resource limit of the process (see +man:getrlimit(2)). + +option:-g 'GROUP', option:--group='GROUP':: + Use 'GROUP' as Unix tracing group (default: `tracing`). option:-w 'PATH', option:--working-directory='PATH':: - Set the working directory of the processes this relay daemon creates. + Set the working directory of the processes the relay daemon creates + to 'PATH'. ++ +See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable. option:-v, option:--verbose:: Increase verbosity. @@ -159,10 +197,27 @@ appending additional `v` letters to the option (that is, `-vv` and `-vvv`). +Output +~~~~~~ +See the <> section above for more +information. + +option:-p, option:--group-output-by-host:: + Group the written trace directories by hostname (default). + +option:-s, option:--group-output-by-session:: + Group the written trace directories by tracing session name instead + of by hostname. + +option:-o 'PATH', option:--output='PATH':: + Set the base output directory of the written trace directories to + 'PATH'. + + Ports ~~~~~ See the <> section above for more information -about the syntax of the following options' 'URL' argument. +about the syntax of the following 'URL' argument. option:-C 'URL', option:--control-port='URL':: Listen to control data on URL 'URL' (default: @@ -197,8 +252,9 @@ ENVIRONMENT VARIABLES of 0 or -1 uses the timeout of the operating system (default). `LTTNG_RELAYD_DISALLOW_CLEAR`:: - Set to 1 to disallow the use of lttng-clear(1) on sessions collected by - this relay daemon. + Set to 1 to disallow clearing operations (see man:lttng-clear(1)). ++ +The option:--disallow-clear option overrides this variable. `LTTNG_RELAYD_HEALTH`:: Path to relay daemon health's socket. @@ -258,7 +314,7 @@ Supported on Linux only. Search for `tcp_keepalive_intvl` in man:tcp(7) for more information. `LTTNG_RELAYD_WORKING_DIRECTORY`:: - Working directory of the processes this relay daemon creates. + Working directory of the processes the relay daemon creates. + The option:--working-directory option overrides this variable. @@ -269,8 +325,8 @@ FILES User LTTng runtime and configuration directory. `$LTTNG_HOME/lttng-traces`:: - Default output directory of LTTng traces. This can be overridden - with the option:--output option. + Default base output directory of LTTng traces. This can be + overridden with the option:--output option. NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.