lttng-relayd(8): normalize style and add details

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ifd2e90686bf9955f0c68fe158c60344d346814d0
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt
index f5a5bcd1067e9593bc4c007dc35a4522f0de268b..99d5b07ed99d4be080ec8a022897e729419562b8 100644 (file)
--- 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 <<output-directory,Output directory>> 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 <<output-directory,Output directory>> 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 <<output-directory,Output directory>> 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 <<output-directory,Output directory>> 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 <<url-format,URL format>> 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.