doc/man: use double quotes when referring to internal section

[lttng-tools.git] / doc / man / lttng-create.1.txt

diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt
index 6ebdcb78a698ba36f6b2a4ad4197ff9f9110e191..4e997e1d10a0720ca3dbaebca0fa35b592c55d13 100644 (file)
--- a/doc/man/lttng-create.1.txt
+++ b/doc/man/lttng-create.1.txt
@@ -1,6 +1,6 @@
 lttng-create(1)
 ===============
-:revdate: 12 May 2021
+:revdate: 17 May 2021
 
 
 NAME
@@ -91,6 +91,8 @@ genoption:--relayd-path option.
 On success, the `create` command sets the current tracing session (see
 man:lttng-concepts(7) to learn more) to the created tracing session.
 
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
+
 Show the status of the current tracing session with the
 man:lttng-status(1) command.
 
@@ -141,7 +143,7 @@ Otherwise:::
 +
 Set the trace output destination with the option:--set-url option, or
 with the option:--ctrl-url and option:--data-url options (see the
-<<url-format,URL format>> section below).
+``<<url-format,URL format>>'' section below).
 
 [[snapshot-mode]]Snapshot mode (option:--snapshot option)::
     Only write the trace data to the local file system or send it to a
@@ -173,8 +175,8 @@ date/time.
 +
 Set the trace output destination with the option:--set-url='URL' option,
 or with the option:--ctrl-url='URL' and option:--data-url='URL' options
-(see the <<url-format,URL format>> section below). 'URL' may :not: start
-with `file://`.
+(see the ``<<url-format,URL format>>'' section below). 'URL' may :not:
+start with `file://`.
 
 
 [[url-format]]
@@ -193,8 +195,8 @@ file://'TRACEDIR'
 +
 The `file://` protocol targets the *local file system*: you may only use
 such an URL with the option:--set-url option when you create the tracing
-session in local or snapshot mode (see the <<modes,Tracing session
-modes>> section above).
+session in local or snapshot mode (see the ``<<modes,Tracing session
+modes>>'' section above).
 +
 'TRACEDIR':::
     Absolute path to the directory containing the trace data on the
@@ -208,7 +210,7 @@ Network format::
 +
 This format is only available when you create the tracing session in
 network streaming, snapshot (option:--snapshot), or live (option:--live)
-mode (see the <<modes,Tracing session modes>> section above).
+mode (see the ``<<modes,Tracing session modes>>'' section above).
 +
 'NETPROTO':::
     Network protocol, amongst:
@@ -266,7 +268,7 @@ include::common-lttng-cmd-options-head.txt[]
 
 Mode selection
 ~~~~~~~~~~~~~~
-See the <<modes,Tracing session modes>> section above.
+See the ``<<modes,Tracing session modes>>'' section above.
 
 At most one of:
 
@@ -318,8 +320,8 @@ date/time.
 Output
 ~~~~~~
 option:--no-output::
-    Depending on the tracing session mode (see the <<modes,Tracing
-    session modes>> section above):
+    Depending on the tracing session mode (see the ``<<modes,Tracing
+    session modes>>'' section above):
 +
 Local mode:::
     Disable the file system output.
@@ -337,15 +339,15 @@ option:--shm-path='DIR'::
 
 URL
 ~~~
-See the <<url-format,URL format>> section above to learn more about the
-syntax of the 'URL' argument of the following options.
+See the ``<<url-format,URL format>>'' section above to learn more about
+the syntax of the 'URL' argument of the following options.
 
 option:-C 'URL', option:--ctrl-url='URL'::
     Set the control path URL to 'URL'.
 +
 You must also use the option:--data-url option.
 +
-Not available in local mode (see the <<modes,Tracing session modes>>
+Not available in local mode (see the ``<<modes,Tracing session modes>>''
 section above).
 +
 In snapshot mode, this is equivalent to using the nloption:--ctrl-url
@@ -357,7 +359,7 @@ option:-D 'URL', option:--data-url='URL'::
 +
 You must also use the option:--ctrl-url option.
 +
-Not available in local mode (see the <<modes,Tracing session modes>>
+Not available in local mode (see the ``<<modes,Tracing session modes>>''
 section above).
 +
 In snapshot mode, this is equivalent to using the nloption:--data-url
@@ -369,8 +371,8 @@ option:-U 'URL', option:--set-url='URL'::
 +
 This URL remains unchanged as long as the tracing session exists.
 +
-Depending on the tracing session mode (see the <<modes,Tracing session
-modes>> section above):
+Depending on the tracing session mode (see the ``<<modes,Tracing session
+modes>>'' section above):
 +
 Local mode:::
     'URL' must start with `file://`, followed with the destination
@@ -392,6 +394,112 @@ include::common-lttng-cmd-help-options.txt[]
 include::common-lttng-cmd-after-options.txt[]
 
 
+[[examples]]
+EXAMPLES
+--------
+.Create a normal mode tracing session with a generated name.
+====
+[role="term"]
+----
+$ lttng create
+----
+====
+
+.Create a normal mode tracing session with a custom name.
+====
+[role="term"]
+----
+$ lttng create my-session
+----
+====
+
+.Create a normal mode tracing session with a specific output directory.
+====
+See the option:--output option.
+
+[role="term"]
+----
+$ lttng create --output=/path/to/traces
+----
+====
+
+.Create a network streaming mode tracing session.
+====
+See the ``Output directory'' section of man:lttng-relayd(8) to
+understand where the relay daemon to connect to (`10.0.0.242`) writes
+the received traces.
+
+See the option:--set-url option.
+
+[role="term"]
+----
+$ lttng create --set-url=net://10.0.0.242/inv4
+----
+====
+
+.Create a snapshot mode tracing session with a default snapshot output.
+====
+See the option:--snapshot option.
+
+[role="term"]
+----
+$ lttng create --snapshot
+----
+====
+
+.Create a snapshot mode tracing session with a custom snapshot output.
+====
+See the option:--snapshot and option:--set-url options.
+
+[role="term"]
+----
+$ lttng create --snapshot \
+        --set-url=tcp://192.168.1.102:1234:5678/my-snapshots
+----
+====
+
+.Create a snapshot mode tracing session with no snapshot output.
+====
+See the option:--snapshot and option:--no-output options.
+
+[role="term"]
+----
+$ lttng create --snapshot --no-output
+----
+====
+
+.Create an LTTng live mode tracing session with a default relay daemon URL.
+====
+See the option:--live option.
+
+[role="term"]
+----
+$ lttng create --live
+----
+====
+
+.Create an LTTng live mode tracing session with a custom live timer period and relay daemon URL.
+====
+See the option:--live and option:--set-url options.
+
+[role="term"]
+----
+$ lttng create --live=250000 \
+               --set-url=tcp://relayd34:4885:4886
+----
+====
+
+.Create a normal mode tracing session with a custom directory containing the ring buffer shared memory files.
+====
+See the option:--shm-path option.
+
+[role="term"]
+----
+$ lttng create my-session --shm-path=/mnt/nvram2/lttng
+----
+====
+
+
 include::common-footer.txt[]