-Creation modes
-~~~~~~~~~~~~~~
-There are four tracing session modes:
-
-Local mode::
- Traces the local system and writes the trace to the local
- file system. The option:--output option specifies the trace path.
- 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
- system (implicit option:--no-output option). Channels are automatically
- configured to be snapshot-ready on creation (see
- man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
- command is used to take snapshots of the current ring buffers.
- The option:--set-url, or option:--ctrl-url and option:--data-url
- options set the default snapshot output destination.
-
-Live mode::
- Traces the local system, sending trace data to an LTTng relay daemon
- 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 the <<url-format,URL format>>
- section below).
+Everything that you do when you control LTTng tracers to record events
+happens within a tracing session. In particular, a tracing session:
+
+* Has its own name.
+
+* Has its own set of trace files, if any.
+
+* Has its own state of activity (started or stopped).
+
+* Has its own mode (local, network streaming,
+ snapshot, or live).
++
+See the <<modes,Tracing session modes>> section below to learn more.
+
+* Has its own channels (see man:lttng-enable-channel(1)) to which are
+ attached their own recording event rules (see
+ man:lttng-enable-event(1)).
+
+* Has its own process attribute tracking inclusion sets (see
+ man:lttng-track(1)).
+
+Without the 'SESSION' argument, LTTng automatically generates a tracing
+session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
+'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may
+:not: contain the character `/`.
+
+Specify the path of the directory containing the shared memory files
+holding the channel ring buffers with the option:--shm-path option.
+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.
+
+List the tracing sessions of your Unix user with the man:lttng-list(1)
+command.
+
+Start and stop a tracing session with the man:lttng-start(1) and
+man:lttng-stop(1) commands.
+
+Save and load a tracing session with the man:lttng-save(1) and
+man:lttng-load(1) commands.
+
+Archive the current trace chunk (rotate) a tracing session with the
+man:lttng-rotate(1) command.
+
+Destroy a tracing session with the man:lttng-destroy(1) command.
+
+
+Current tracing session
+~~~~~~~~~~~~~~~~~~~~~~~
+When you run the `create` command, LTTng creates the
+`$LTTNG_HOME/.lttngrc` file if it doesn't exist (`$LTTNG_HOME` defaults
+to `$HOME`).
+
+`$LTTNG_HOME/.lttngrc` contains the name of the _current tracing
+session_.
+
+When you create a new tracing session with the `create` command, LTTng
+updates the current tracing session.
+
+The following man:lttng(1) commands select the current tracing session
+if you don't specify one:
+
+* man:lttng-add-context(1)
+* man:lttng-clear(1)
+* man:lttng-destroy(1)
+* man:lttng-disable-channel(1)
+* man:lttng-disable-event(1)
+* man:lttng-disable-rotation(1)
+* man:lttng-enable-channel(1)
+* man:lttng-enable-event(1)
+* man:lttng-enable-rotation(1)
+* man:lttng-regenerate(1)
+* man:lttng-rotate(1)
+* man:lttng-save(1)
+* man:lttng-snapshot(1)
+* man:lttng-start(1)
+* man:lttng-status(1)
+* man:lttng-stop(1)
+* man:lttng-track(1)
+* man:lttng-untrack(1)
+* man:lttng-view(1)
+
+Set the current tracing session manually with the
+man:lttng-set-session(1) command, without having to edit the `.lttngrc`
+file.
+
+
+[[modes]]
+Tracing session modes
+~~~~~~~~~~~~~~~~~~~~~
+LTTng offers four tracing session modes:
+
+[[local-mode]]Local mode::
+ Write the trace data to the local file system.
++
+The option:--output option specifies the trace path. Using
+option:--set-url=++file://++__DIR__ is equivalent to using
+option:--output='DIR'.
++
+Disable the file system output with the
+option:--no-output option.
++
+If you don't use any of the option:--output, option:--set-url, or
+option:--no-output options, then LTTng writes the trace data locally to
+the `$LTTNG_HOME/lttng-traces` directory (`$LTTNG_HOME` defaults to
+`$HOME`).
+
+[[network-streaming-mode]]Network streaming mode::
+ Send the trace data over the network to a listening relay daemon
+ (see man:lttng-relayd(8)).
++
+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).
+
+[[snapshot-mode]]Snapshot mode (option:--snapshot option)::
+ Don't write the trace data to the local file system by default
+ (implicit option:--no-output option): only write the trace data to
+ the local file system or send it to a listening relay daemon
+ (man:lttng-relayd(8)) when LTTng takes a snapshot.
++
+LTTng automatically configures the channels of such a tracing session to
+be snapshot-ready on creation (see man:lttng-enable-channel(1)).
++
+LTTng takes a snapshot of such a tracing session when:
++
+--
+* You run the man:lttng-snapshot(1) command.
+* LTTng executes a `snapshot-session` trigger action (see
+ man:lttng-add-trigger(1)).
+--
++
+Set the default snapshot 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).
+
+[[live-mode]]Live mode (option:--live option)::
+ Send the trace data over the network to a listening relay daemon
+ (see man:lttng-relayd(8)) for live reading.
++
+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://`.