X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-create.1.txt;h=a1bf9d80e34fecfbda8d3d26adfff99bfc4e4ab9;hb=ebbd679f2e8b43e48ac97d76a7fe13fc4f44e576;hp=daac924f7d369cf8e72bbda1841fa3ff3bfc09ba;hpb=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66;p=lttng-tools.git

diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt
index daac924f7..a1bf9d80e 100644
--- a/doc/man/lttng-create.1.txt
+++ b/doc/man/lttng-create.1.txt
@@ -1,6 +1,6 @@
 lttng-create(1)
 ===============
-:revdate: 3 May 2021
+:revdate: 17 May 2021
 
 
 NAME
@@ -55,15 +55,44 @@ Specifying a location on an NVRAM file system makes it possible to
 recover the latest recorded trace data when the system reboots after a
 crash with the man:lttng-crash(1) utility.
 
-By default, the `create` command automatically spawns a session daemon
-for your Unix user if none is currently running. Override the path of
-the session daemon binary to spawn with the general
-genoption:--sessiond-path option. Avoid automatically spawning a session
-daemon with the general genoption:--no-sessiond option.
+By default, the `create` command automatically spawns:
+
+* A session daemon for your Unix user if none is currently running.
++
+Override the path of the session daemon binary to spawn with the
+general genoption:--sessiond-path option.
++
+Avoid automatically spawning a session daemon with the general
+genoption:--no-sessiond option.
+
+* A relay daemon (see man:lttng-relayd(8)) if all the following
+  statements are true:
++
+--
+* You specify the option:--live option.
+
+* You don't specify any of the option:--set-url, option:--ctrl-url, or
+  option:--data-url options.
+
+* No relay daemon is currently listening for TCP connections on
+  +127.0.0.1:{default_network_viewer_port}+ (default LTTng live reader
+  connection address and port).
+--
++
+In this case, the `create` command spawns a relay daemon as such:
++
+[verse]
+*lttng-relayd* nloption:--live-port=**tcp://localhost:{default_network_viewer_port}**
+{nbsp}
++
+Override the path of the relay daemon binary to spawn with the general
+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.
 
@@ -234,7 +263,7 @@ This path is relative to the base output directory of the LTTng relay
 daemon (see the nloption:--output option of man:lttng-relayd(8)).
 
 
-include::common-cmd-options-head.txt[]
+include::common-lttng-cmd-options-head.txt[]
 
 
 Mode selection
@@ -359,24 +388,133 @@ Snapshot mode (option:--snapshot option):::
     after creating the tracing session.
 
 
-include::common-cmd-help-options.txt[]
+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
+----
+====
 
-include::common-cmd-footer.txt[]
+.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[]
 
 
 SEE ALSO
 --------
 man:lttng(1),
-man:lttng-concepts(7),
 man:lttng-destroy(1),
 man:lttng-enable-channel(1),
-man:lttng-list(8),
-man:lttng-relayd(8),
+man:lttng-list(1),
 man:lttng-rotate(1),
 man:lttng-save(1),
-man:lttng-sessiond(8),
 man:lttng-set-session(1),
 man:lttng-start(1),
-man:lttng-status(8),
-man:lttng-track(1)
+man:lttng-status(1),
+man:lttng-track(1),
+man:lttng-concepts(7),
+man:lttng-relayd(8),
+man:lttng-sessiond(8)