lttng-create(1)
===============
-:revdate: 8 April 2021
+:revdate: 7 December 2021
NAME
----
-lttng-create - Create an LTTng tracing session
+lttng-create - Create an LTTng recording session
SYNOPSIS
--------
-Create a local mode tracing session:
+Create a local mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
- [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR']
+ [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
-Create a network streaming mode tracing session:
+Create a network streaming mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
(option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
-Create a snapshot mode tracing session:
+Create a snapshot mode recording session:
[verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot
- [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot [option:--shm-path='DIR']
+ [option:--no-output | option:--output='DIR' | option:--set-url='URL' |
+ option:--ctrl-url='URL' option:--data-url='URL']
-Create a live mode tracing session:
+Create a live mode recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
DESCRIPTION
-----------
-The `lttng create` command creates a new tracing session for your Unix
-user.
+The `lttng create` command creates a new recording session for your Unix
+user within the connected session daemon (see the ``Session daemon
+connection'' section of man:lttng(1) to learn how a user application
+connects to a session daemon).
-A tracing session is a stateful dialogue between you and a
-session daemon (see man:lttng-sessiond(8)) for everything related to
-event recording.
+See man:lttng-concepts(7) to learn more about recording sessions.
-Everything that you do when you control LTTng tracers to record events
-happens within a tracing session. In particular, a tracing session:
+Without the 'SESSION' argument, LTTng automatically generates a recording
+session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
+'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may
+:not: contain the character `/`.
-* Has its own name.
+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. Note that, as of
+LTTng{nbsp}{lttng_version}, this feature is only available for user
+space channels.
-* Has its own set of trace files, if any.
+By default, the `create` command automatically spawns:
-* Has its own state of activity (started or stopped).
+* 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.
-* Has its own mode (local, network streaming,
- snapshot, or live).
+* A relay daemon (see man:lttng-relayd(8)) if all the following
+ statements are true:
+
-See the <<modes,Tracing session modes>> section below to learn more.
+--
+* You specify the option:--live option.
-* 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)).
+* You don't specify any of the option:--set-url, option:--ctrl-url, or
+ option:--data-url options.
-* Has its own process attribute tracking inclusion sets (see
- man:lttng-track(1)).
+* 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.
-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 `/`.
+On success, the `create` command sets the current recording session (see
+man:lttng-concepts(7) to learn more) to the created recording session.
-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.
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-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.
+Show the status of the current recording session with the
+man:lttng-status(1) command.
-List the tracing sessions of your Unix user with the man:lttng-list(1)
-command.
+List the recording sessions of your Unix user, or of all users if
+your Unix user is `root`, within the connected session daemon with the
+man:lttng-list(1) command.
-Start and stop a tracing session with the man:lttng-start(1) and
+Start and stop a recording 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
+Save and load a recording 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.
+Allow and disallow specific processes to record events with the
+man:lttng-track(1) and man:lttng-untrack(1) commands.
+Archive the current trace chunk of (rotate) a recording session with the
+man:lttng-rotate(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.
+Destroy a recording session with the man:lttng-destroy(1) command.
[[modes]]
-Tracing session modes
-~~~~~~~~~~~~~~~~~~~~~
-LTTng offers four tracing session modes:
+Recording session modes
+~~~~~~~~~~~~~~~~~~~~~~~
+As documented in man:lttng-concepts(7), LTTng offers four recording
+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.
+The trace data output directory is:
+
-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`).
+With the option:--no-output option:::
+ None: the file system output is disabled.
+
+With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
+ The directory 'DIR'.
+
+Otherwise:::
+ A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
+ defaults to `$HOME`) directory, of which the name contains the
+ recording session name and the date/time.
[[network-streaming-mode]]Network streaming mode::
Send the trace data over the network to a listening relay daemon
+
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)::
- 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)).
+ 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 (see the man:lttng-snapshot(1) command).
+
-LTTng takes a snapshot of such a tracing session when:
+With this mode, LTTng:
+
---
-* You run the man:lttng-snapshot(1) command.
-* LTTng executes a `snapshot-session` trigger action (see
- man:lttng-add-trigger(1)).
---
+With the option:--no-output option:::
+ Does :not: add any snapshot output to the created recording
+ session.
+
+With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
+ Adds a snapshot output named `snapshot-1` using the provided
+ path or URL(s) to the created recording session.
+
+Otherwise:::
+ Adds an automatic snapshot output named `snapshot-1` to the created
+ recording session.
+
-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).
+The automatic snapshot output is a subdirectory, under the
+`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
+directory, of which the name contains the recording session name and the
+date/time.
[[live-mode]]Live mode (option:--live option)::
Send the trace data over the network to a listening relay daemon
+
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]]
URL format
~~~~~~~~~~
-The argument of the option:--set-url, option:--ctrl-url, and
-option:--data-url options is an URL.
+The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
+option:--data-url='URL' options is an URL.
-There are two available URL formats.
+There are two available 'URL' formats.
Local format::
+
{nbsp}
+
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).
+such an URL with the option:--set-url option when you create the
+recording session in local or snapshot mode (see the ``<<modes,Recording
+session modes>>'' section above).
+
'TRACEDIR':::
Absolute path to the directory containing the trace data on the
'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
{nbsp}
+
-This format is only available when you create the tracing session in
-network streaming, snapshot, or live mode (see the <<modes,Tracing
-session modes>> section above).
+This format is only available when you create the recording session in
+network streaming, snapshot (option:--snapshot), or live (option:--live)
+mode (see the ``<<modes,Recording session modes>>'' section above).
+
'NETPROTO':::
Network protocol, amongst:
--
+
('HOST' | 'IPADDR'):::
- Hostname or IP address (IPv6 address *must* be enclosed in square
- brackets (`[` and{nbsp}`]`); see
- https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]).
+ Hostname or IP address.
++
+IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
+see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
'CTRLPORT':::
Control TCP port.
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
~~~~~~~~~~~~~~
-See the <<modes,Tracing session modes>> section above.
+See the ``<<modes,Recording session modes>>'' section above.
At most one of:
option:--live[='DELAYUS']::
- Create the tracing session in live mode.
+ Create the recording session in live mode.
+
The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
for the data to be flushed (sent to the connected LTTng relay daemon).
(see man:lttng-relayd(8)).
option:--snapshot::
- Create the tracing session in snapshot mode.
+ Create the recording session in snapshot mode.
++
+This is equivalent to:
++
+* One of:
+
-This is equivalent to using the option:--no-output option and creating
-all the channels of this new tracing session with the
-nloption:--override and nloption:--output=++mmap++ options (see
-man:lttng-enable-channel(1)).
+--
+With the option:--no-output option::
+ Not adding any snapshot output after LTTng creates the recording
+ session.
+
+With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
+ Adding a snapshot output named `snapshot-1` using the provided path
+ or URL(s) immediately after LTTng creates the recording session.
+
+Otherwise::
+ Adding an automatic snapshot output named `snapshot-1` immediately
+ after LTTng creates the recording session.
++
+The automatic snapshot output is a subdirectory, under the
+`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
+directory, of which the name contains the recording session name and the
+date/time.
+--
+
+* Forcing all the channels to be created for the recording session to be
+ configured with the nloption:--override and nloption:--output=++mmap++
+ options (see man:lttng-enable-channel(1)).
Output
~~~~~~
option:--no-output::
- In local mode (see the <<modes,Tracing session modes>> section
- above), do :not: write any trace data.
+ Depending on the recording session mode (see the ``<<modes,Recording
+ session modes>>'' section above):
+
-You may :not: use this option with the option:--output option.
+Local mode:::
+ Disable the file system output.
+
+Snapshot mode (option:--snapshot option):::
+ Do :not: add a snapshot output after creating the recording session.
option:-o 'DIR', option:--output='DIR'::
- In local mode, set the trace output path to 'DIR'.
-+
-You may :not: use this option with the option:--no-output option.
+ Equivalent to option:--set-url=++file://++__DIR__.
option:--shm-path='DIR'::
Set the path of the directory containing the shared memory files
holding the channel ring buffers to 'DIR' on the local file sytem.
++
+NOTE: As of LTTng{nbsp}{lttng_version}, LTTng only considers this option
+for user space (including Java and Python) channels, but this may change
+in the future.
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,Recording session
+modes>>'' section above).
++
+In snapshot mode, this is equivalent to using the nloption:--ctrl-url
+option of the `add-output` action of the man:lttng-snapshot(1) command
+immediately after creating the recording session.
option:-D 'URL', option:--data-url='URL'::
Set the trace data path URL to 'URL'.
+
You must also use the option:--ctrl-url option.
++
+Not available in local mode (see the ``<<modes,Recording session
+modes>>'' section above).
++
+In snapshot mode, this is equivalent to using the nloption:--data-url
+option of the `add-output` action of the man:lttng-snapshot(1) command
+immediately after creating the recording session.
option:-U 'URL', option:--set-url='URL'::
Set the destination URL of the control path and trace data to 'URL'.
+
-This URL stays the same as long as the tracing session exists.
+This URL remains unchanged as long as the recording session exists.
++
+Depending on the recording session mode (see the ``<<modes,Recording
+session modes>>'' section above):
+
-In local mode (see the <<modes,Tracing session modes>> section above),
-'URL' must start with `file://`, followed with the destination directory
-path on the local file system.
+Local mode:::
+ 'URL' must start with `file://`, followed with the destination
+ directory path on the local file system.
+
+Network streaming and live modes:::
+ Equivalent to using both the option:--ctrl-url and option:--data-url
+ options.
+
+Snapshot mode (option:--snapshot option):::
+ Equivalent to using the 'URL' non-option argument of the
+ `add-output` action of the man:lttng-snapshot(1) command immediately
+ after creating the recording session.
+
+
+include::common-lttng-cmd-help-options.txt[]
+
+include::common-lttng-cmd-after-options.txt[]
-include::common-cmd-help-options.txt[]
+[[examples]]
+EXAMPLES
+--------
+.Create a normal mode recording session with a generated name.
+====
+[role="term"]
+----
+$ lttng create
+----
+====
+
+.Create a normal mode recording session with a custom name.
+====
+[role="term"]
+----
+$ lttng create my-session
+----
+====
-include::common-cmd-footer.txt[]
+.Create a normal mode recording session with a specific output directory.
+====
+See the option:--output option.
+
+[role="term"]
+----
+$ lttng create --output=/path/to/traces
+----
+====
+
+.Create a network streaming mode recording 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 recording session with a default snapshot output.
+====
+See the option:--snapshot option.
+
+[role="term"]
+----
+$ lttng create --snapshot
+----
+====
+
+.Create a snapshot mode recording 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 recording 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 recording session with a default relay daemon URL.
+====
+See the option:--live option.
+
+[role="term"]
+----
+$ lttng create --live
+----
+====
+
+.Create an LTTng live mode recording 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 recording 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-destroy(1),
man:lttng-enable-channel(1),
-man:lttng-relayd(8),
+man:lttng-list(1),
man:lttng-rotate(1),
-man:lttng-sessiond(8),
+man:lttng-save(1),
man:lttng-set-session(1),
man:lttng-start(1),
-man:lttng-stop(1),
-man:lttng-track(1)
+man:lttng-status(1),
+man:lttng-track(1),
+man:lttng-concepts(7),
+man:lttng-relayd(8),
+man:lttng-sessiond(8)