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]]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]]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]]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]]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 when the session is
 122 created in <<local-mode,local>> or <<snapshot-mode,snapshot>> mode.
 123
 124 'TRACEPATH'::
 125     Absolute path to trace files on the local file system.
 126
 127 The other version is available when the session is created in
 128 <<network-streaming-mode,network streaming>>,
 129 <<snapshot-mode,snapshot>>, or <<live-mode,live>> mode.
 130
 131 'NETPROTO'::
 132     Network protocol, amongst:
 133 +
 134 --
 135 `net`::
 136     TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
 137     are resp. 5342 and 5343.
 138
 139 `net6`::
 140     TCP over IPv6: same default ports as the `net` protocol.
 141
 142 `tcp`::
 143     Same as the `net` protocol; can only be used with the
 144     option:--ctrl-url and option:--data-url options together.
 145
 146 `tcp6`::
 147     Same as the `net6` protocol; can only be used with the
 148     option:--ctrl-url and option:--data-url options together.
 149 --
 150
 151 ('HOST' | 'IPADDR')::
 152     Hostname or IP address (IPv6 address *must* be enclosed in brackets
 153     (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
 154
 155 'CTRLPORT'::
 156     Control port.
 157
 158 'DATAPORT'::
 159     Data port.
 160
 161 'TRACEPATH'::
 162     Path of trace files on the remote file system. This path is relative
 163     to the base output directory set on the relay daemon side;
 164     see man:lttng-relayd(8).
 165
 166
 167 include::common-cmd-options-head.txt[]
 168
 169
 170 Mode selection
 171 ~~~~~~~~~~~~~~
 172 option:--live[='DELAYUS']::
 173     Create the session in <<live-mode,live mode>>.
 174 +
 175 The optional 'DELAYUS' parameter, given in microseconds, is the
 176 maximum time the user can wait for the data to be flushed. This mode
 177 can be set with a network URL (options option:--set-url, or
 178 option:--ctrl-url and option:--data-url) and must have a relay
 179 daemon listening (see man:lttng-relayd(8)).
 180 +
 181 By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
 182 is set to `net://127.0.0.1`.
 183
 184 option:--snapshot::
 185     Create the session in <<snapshot-mode,snapshot mode>>.
 186     This is the equivalent of using the option:--no-output option and
 187     creating all the channels of this new tracing session in overwrite
 188     mode with an `mmap` output type.
 189
 190
 191 Output
 192 ~~~~~~
 193 option:--no-output::
 194     In <<local-mode,local mode>>, do not output any trace data.
 195
 196 option:-o, option:--output='PATH'::
 197     In <<local-mode,local mode>>, set trace output path to 'PATH'.
 198
 199 option:--shm-path='PATH'::
 200     Create shared memory holding buffers at 'PATH'.
 201
 202
 203 URL
 204 ~~~
 205 See the <<url-format,URL format>> section above for more information
 206 about the syntax of the following options' 'URL' argument.
 207
 208 option:-C, option:--ctrl-url='URL'::
 209     Set control path URL to 'URL' (must use option:--data-url option
 210     also).
 211
 212 option:-D, option:--data-url='URL'::
 213     Set data path URL to 'URL' (must use option:--ctrl-url option
 214     also).
 215
 216 option:-U, option:--set-url='URL'::
 217     Set URL destination of the trace data to 'URL'. It is persistent for
 218     the session lifetime. This option sets both data
 219     (option:--data-url option) and control (option:--ctrl-url option)
 220     URLs at the same time.
 221 +
 222 In <<local-mode,local>> mode, 'URL' must start with `file://` followed
 223 by the destination path on the local file system.
 224
 225
 226 include::common-cmd-help-options.txt[]
 227
 228
 229 include::common-cmd-footer.txt[]
 230
 231
 232 SEE ALSO
 233 --------
 234 man:lttng-destroy(1),
 235 man:lttng-set-session(1),
 236 man:lttng(1)