From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Wed, 18 May 2016 00:57:20 +0000 (-0400)
Subject: lttng-create(1): add relay mode
X-Git-Tag: v2.9.0-rc1~166
X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=f87c475639158070c4eeecede46ed46035ac57bd;p=lttng-tools.git

lttng-create(1): add relay mode

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

diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt
index 05ff4d64e..10d0c0a75 100644
--- a/doc/man/lttng-create.1.txt
+++ b/doc/man/lttng-create.1.txt
@@ -9,25 +9,29 @@ lttng-create - Create an LTTng tracing session
 
 SYNOPSIS
 --------
-Normal mode:
+Local mode:
 
 [verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--output='PATH' | option:--no-output]
-      [option:--shm-path='PATH'] ['SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
+      [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH'] ['SESSION']
+
+Network streaming mode:
+
+[verse]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
+      (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') ['SESSION']
 
 Snapshot mode:
 
 [verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--snapshot
-      [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
-      [option:--shm-path='PATH'] ['SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--snapshot [option:--shm-path='PATH']
+      [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
 
 Live mode:
 
 [verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--live[='DELAYUS']
-      [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
-      [option:--shm-path='PATH'] ['SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--live[='DELAYUS'] [option:--shm-path='PATH']
+      [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
 
 
 DESCRIPTION
@@ -63,14 +67,25 @@ command.
 
 Creation modes
 ~~~~~~~~~~~~~~
-There are three tracing session modes:
+There are four tracing session modes:
 
-Normal mode::
+Local mode::
     Traces the local system and writes the trace to the local
     file system. The option:--output option specifies the trace path.
-    If omitted, the trace is written in the `$LTTNG_HOME/lttng-traces`
-    directory (`$LTTNG_HOME` defaults to `$HOME`). The file system
-    output can be disabled using the option:--no-output option.
+    Using option:--set-url=file://'PATH' is the equivalent of using
+    option:--output='PATH'. The file system output can be disabled using
+    the option:--no-output option.
++
+If none of the options mentioned above are used, then the trace is
+written locally in the `$LTTNG_HOME/lttng-traces` directory
+(`$LTTNG_HOME` defaults to `$HOME`).
+
+Network streaming mode::
+    Traces the local system and sends the trace over the network to
+    a listening relay daemon (see man:lttng-relayd(8)).
+    The option:--set-url, or option:--ctrl-url and option:--data-url
+    options set the trace output destination (see the
+    <<url-format,URL format>> section below).
 
 Snapshot mode::
     Traces the local system without writing the trace to the local file
@@ -86,14 +101,15 @@ Live mode::
     over the network (see man:lttng-relayd(8)). The
     option:--set-url, or option:--ctrl-url and option:--data-url options
     set the trace output destination. The live output URLs cannot use
-    the `file://` protocol (see URL format below).
+    the `file://` protocol (see the <<url-format,URL format>>
+    section below).
 
 
 [[url-format]]
 URL format
 ~~~~~~~~~~
-The option:--set-url, option:--ctrl-url, and option:--data-url options
-specify URLs.
+The option:--set-url, option:--ctrl-url, and option:--data-url options'
+arguments are URLs.
 
 The format of those URLs is one of:
 
@@ -101,12 +117,13 @@ The format of those URLs is one of:
 file://'TRACEPATH'
 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
 
-The `file://` protocol targets the *local file system*.
+The `file://` protocol targets the *local file system* and can only
+be used as the option:--set-url option's argument in _local mode_.
 
 'TRACEPATH'::
     Absolute path to trace files on the local file system.
 
-The other version is used for *network streaming*.
+The other version is used for the _network streaming mode_.
 
 'NETPROTO'::
     Network protocol, amongst:
@@ -138,8 +155,8 @@ The other version is used for *network streaming*.
 include::common-cmd-options-head.txt[]
 
 
-Mode
-~~~~
+Mode selection
+~~~~~~~~~~~~~~
 option:--live[='DELAYUS']::
     Create the session in live mode. The optional 'DELAYUS' parameter,
     given in microseconds, is the maximum time the user can wait for