lttng-create(1): use def list for net protocols

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

lttng-create(1)
===============


NAME
----
lttng-create - Create an LTTng tracing session


SYNOPSIS
--------
Local mode:

[verse]
*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:--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:--shm-path='PATH']
      [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']


DESCRIPTION
-----------
The `lttng create` command creates a new tracing session.

A tracing session is a named container of channels, which in turn
contain event rules. It is domain-agnostic, in that channels and event
rules can be enabled for the user space tracer and/or the Linux
kernel tracer.

On execution, an `.lttngrc` file is created, if it does not exist, in the
user's home directory. This file contains the name of the current tracing
session. When creating a new tracing session with `lttng create`, the
current tracing session is set to this new tracing session. The
man:lttng-set-session(1) command can be used to set the current
tracing session without manually editing the `.lttngrc` file.

If 'SESSION' is omitted, a session name is automatically created having
this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
character `/`.

The option:--shm-path option can be used to specify the path to the
shared memory holding the ring buffers. Specifying a location on an
NVRAM file system makes it possible to retrieve the latest recorded
trace data when the system reboots after a crash. To view the events
of ring buffer files after a system crash, use the
man:lttng-crash(1) utility.

Tracing sessions are destroyed using the man:lttng-destroy(1)
command.


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).


[[url-format]]
URL format
~~~~~~~~~~
The option:--set-url, option:--ctrl-url, and option:--data-url options'
arguments are URLs.

The format of those URLs is one of:

[verse]
file://'TRACEPATH'
'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']

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 the _network streaming mode_.

'NETPROTO'::
    Network protocol, amongst:
+
--
`net`::
    TCP over IPv4; the default values of `<ctrl port>` and `<data port>`
    are resp. 5342 and 5343.

`net6`::
    TCP over IPv6: same default ports as the `net` protocol.

`tcp`::
    Same as the `net` protocol; can only be used with the
    option:--ctrl-url and option:--data-url options together.

`tcp6`::
    Same as the `net6` protocol; can only be used with the
    option:--ctrl-url and option:--data-url options together.
--

('HOST' | 'IPADDR')::
    Hostname or IP address (IPv6 address *must* be enclosed in brackets
    (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).

'CTRLPORT'::
    Control port.

'DATAPORT'::
    Data port.

'TRACEPATH'::
    Path of trace files on the remote file system. This path is relative
    to the base output directory set on the relay daemon side;
    see man:lttng-relayd(8).


include::common-cmd-options-head.txt[]


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
    the data to be flushed. This mode can be set with a network URL
    (options option:--set-url, or option:--ctrl-url and option:--data-url)
    and must have a relay daemon listening (see man:lttng-relayd(8)).
+
By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
is set to `net://127.0.0.1`.

option:--snapshot::
    Create the session in snapshot mode. This is the equivalent of using
    the option:--no-output option and creating all the channels of this
    new tracing session in overwrite mode with an `mmap` output type.


Output
~~~~~~
option:--no-output::
    Do not output any trace data.

option:-o, option:--output='PATH'::
    Set trace output path to 'PATH'.

option:--shm-path='PATH'::
    Create shared memory holding buffers at 'PATH'.


URL
~~~
See the <<url-format,URL format>> section above for more information
about the syntax of the following options' 'URL' argument.

option:-C, option:--ctrl-url='URL'::
    Set control path URL to 'URL' (must use option:--data-url option
    also).

option:-D, option:--data-url='URL'::
    Set data path URL to 'URL' (must use option:--ctrl-url option
    also).

option:-U, option:--set-url='URL'::
    Set URL destination of the trace data to 'URL'. It is persistent for
    the session lifetime. This option sets both data
    (option:--data-url option) and control (option:--ctrl-url option)
    URLs at the same time.


include::common-cmd-help-options.txt[]


include::common-cmd-footer.txt[]


SEE ALSO
--------
man:lttng-destroy(1),
man:lttng-set-session(1),
man:lttng(1)