doc/man/lttng-create.1.txt

   1 lttng-create(1)
   2 ===============
   3
   4
   5 NAME
   6 ----
   7 lttng-create - Create an LTTng tracing session
   8
   9
  10 SYNOPSIS
  11 --------
  12 Local mode:
  13
  14 [verse]
  15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
  16       [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH'] ['SESSION']
  17
  18 Network streaming mode:
  19
  20 [verse]
  21 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
  22       (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') ['SESSION']
  23
  24 Snapshot mode:
  25
  26 [verse]
  27 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--snapshot [option:--shm-path='PATH']
  28       [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
  29
  30 Live mode:
  31
  32 [verse]
  33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--live[='DELAYUS'] [option:--shm-path='PATH']
  34       [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
  35
  36
  37 DESCRIPTION
  38 -----------
  39 The `lttng create` command creates a new tracing session.
  40
  41 A tracing session is a named container of channels, which in turn
  42 contain event rules. It is domain-agnostic, in that channels and event
  43 rules can be enabled for the user space tracer and/or the Linux
  44 kernel tracer.
  45
  46 On execution, an `.lttngrc` file is created, if it does not exist, in the
  47 user's home directory. This file contains the name of the current tracing
  48 session. When creating a new tracing session with `lttng create`, the
  49 current tracing session is set to this new tracing session. The
  50 man:lttng-set-session(1) command can be used to set the current
  51 tracing session without manually editing the `.lttngrc` file.
  52
  53 If 'SESSION' is omitted, a session name is automatically created having
  54 this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
  55 character `/`.
  56
  57 The option:--shm-path option can be used to specify the path to the
  58 shared memory holding the ring buffers. Specifying a location on an
  59 NVRAM file system makes it possible to retrieve the latest recorded
  60 trace data when the system reboots after a crash. To view the events
  61 of ring buffer files after a system crash, use the
  62 man:lttng-crash(1) utility.
  63
  64 Tracing sessions are destroyed using the man:lttng-destroy(1)
  65 command.
  66
  67
  68 Creation modes
  69 ~~~~~~~~~~~~~~
  70 There are four tracing session modes:
  71
  72 Local mode::
  73     Traces the local system and writes the trace to the local
  74     file system. The option:--output option specifies the trace path.
  75     Using option:--set-url=file://'PATH' is the equivalent of using
  76     option:--output='PATH'. The file system output can be disabled using
  77     the option:--no-output option.
  78 +
  79 If none of the options mentioned above are used, then the trace is
  80 written locally in the `$LTTNG_HOME/lttng-traces` directory
  81 (`$LTTNG_HOME` defaults to `$HOME`).
  82
  83 Network streaming mode::
  84     Traces the local system and sends the trace over the network to
  85     a listening relay daemon (see man:lttng-relayd(8)).
  86     The option:--set-url, or option:--ctrl-url and option:--data-url
  87     options set the trace output destination (see the
  88     <<url-format,URL format>> section below).
  89
  90 Snapshot mode::
  91     Traces the local system without writing the trace to the local file
  92     system (implicit option:--no-output option). Channels are automatically
  93     configured to be snapshot-ready on creation (see
  94     man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
  95     command is used to take snapshots of the current ring buffers.
  96     The option:--set-url, or option:--ctrl-url and option:--data-url
  97     options set the default snapshot output destination.
  98
  99 Live mode::
 100     Traces the local system, sending trace data to an LTTng relay daemon
 101     over the network (see man:lttng-relayd(8)). The
 102     option:--set-url, or option:--ctrl-url and option:--data-url options
 103     set the trace output destination. The live output URLs cannot use
 104     the `file://` protocol (see the <<url-format,URL format>>
 105     section below).
 106
 107
 108 [[url-format]]
 109 URL format
 110 ~~~~~~~~~~
 111 The option:--set-url, option:--ctrl-url, and option:--data-url options'
 112 arguments are URLs.
 113
 114 The format of those URLs is one of:
 115
 116 [verse]
 117 file://'TRACEPATH'
 118 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
 119
 120 The `file://` protocol targets the *local file system* and can only
 121 be used as the option:--set-url option's argument in _local mode_.
 122
 123 'TRACEPATH'::
 124     Absolute path to trace files on the local file system.
 125
 126 The other version is used for the _network streaming mode_.
 127
 128 'NETPROTO'::
 129     Network protocol, amongst:
 130 +
 131 --
 132 `net`::
 133     TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
 134     are resp. 5342 and 5343.
 135
 136 `net6`::
 137     TCP over IPv6: same default ports as the `net` protocol.
 138
 139 `tcp`::
 140     Same as the `net` protocol; can only be used with the
 141     option:--ctrl-url and option:--data-url options together.
 142
 143 `tcp6`::
 144     Same as the `net6` protocol; can only be used with the
 145     option:--ctrl-url and option:--data-url options together.
 146 --
 147
 148 ('HOST' | 'IPADDR')::
 149     Hostname or IP address (IPv6 address *must* be enclosed in brackets
 150     (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
 151
 152 'CTRLPORT'::
 153     Control port.
 154
 155 'DATAPORT'::
 156     Data port.
 157
 158 'TRACEPATH'::
 159     Path of trace files on the remote file system. This path is relative
 160     to the base output directory set on the relay daemon side;
 161     see man:lttng-relayd(8).
 162
 163
 164 include::common-cmd-options-head.txt[]
 165
 166
 167 Mode selection
 168 ~~~~~~~~~~~~~~
 169 option:--live[='DELAYUS']::
 170     Create the session in live mode. The optional 'DELAYUS' parameter,
 171     given in microseconds, is the maximum time the user can wait for
 172     the data to be flushed. This mode can be set with a network URL
 173     (options option:--set-url, or option:--ctrl-url and option:--data-url)
 174     and must have a relay daemon listening (see man:lttng-relayd(8)).
 175 +
 176 By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
 177 is set to `net://127.0.0.1`.
 178
 179 option:--snapshot::
 180     Create the session in snapshot mode. This is the equivalent of using
 181     the option:--no-output option and creating all the channels of this
 182     new tracing session in overwrite mode with an `mmap` output type.
 183
 184
 185 Output
 186 ~~~~~~
 187 option:--no-output::
 188     Do not output any trace data.
 189
 190 option:-o, option:--output='PATH'::
 191     Set trace output path to 'PATH'.
 192
 193 option:--shm-path='PATH'::
 194     Create shared memory holding buffers at 'PATH'.
 195
 196
 197 URL
 198 ~~~
 199 See the <<url-format,URL format>> section above for more information
 200 about the syntax of the following options' 'URL' argument.
 201
 202 option:-C, option:--ctrl-url='URL'::
 203     Set control path URL to 'URL' (must use option:--data-url option
 204     also).
 205
 206 option:-D, option:--data-url='URL'::
 207     Set data path URL to 'URL' (must use option:--ctrl-url option
 208     also).
 209
 210 option:-U, option:--set-url='URL'::
 211     Set URL destination of the trace data to 'URL'. It is persistent for
 212     the session lifetime. This option sets both data
 213     (option:--data-url option) and control (option:--ctrl-url option)
 214     URLs at the same time.
 215
 216
 217 include::common-cmd-help-options.txt[]
 218
 219
 220 include::common-cmd-footer.txt[]
 221
 222
 223 SEE ALSO
 224 --------
 225 man:lttng-destroy(1),
 226 man:lttng-set-session(1),
 227 man:lttng(1)