doc/man/lttng-create.1.txt

   1 lttng-create(1)
   2 ===============
   3 :revdate: 18 January 2018
   4
   5
   6 NAME
   7 ----
   8 lttng-create - Create an LTTng tracing session
   9
  10
  11 SYNOPSIS
  12 --------
  13 Local mode:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH']
  17       [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH']
  18
  19 Network streaming mode:
  20
  21 [verse]
  22 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH']
  23       (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
  24
  25 Snapshot mode:
  26
  27 [verse]
  28 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot
  29       [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
  30
  31 Live mode:
  32
  33 [verse]
  34 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
  35       [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
  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 respectively {default_network_control_port} and
 138     {default_network_data_port}.
 139
 140 `net6`::
 141     TCP over IPv6: same default ports as the `net` protocol.
 142
 143 `tcp`::
 144     Same as the `net` protocol; can only be used with the
 145     option:--ctrl-url and option:--data-url options together.
 146
 147 `tcp6`::
 148     Same as the `net6` protocol; can only be used with the
 149     option:--ctrl-url and option:--data-url options together.
 150 --
 151
 152 ('HOST' | 'IPADDR')::
 153     Hostname or IP address (IPv6 address *must* be enclosed in brackets
 154     (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
 155
 156 'CTRLPORT'::
 157     Control port.
 158
 159 'DATAPORT'::
 160     Data port.
 161
 162 'TRACEPATH'::
 163     Path of trace files on the remote file system. This path is relative
 164     to the base output directory set on the relay daemon side;
 165     see man:lttng-relayd(8).
 166
 167
 168 include::common-cmd-options-head.txt[]
 169
 170
 171 Mode selection
 172 ~~~~~~~~~~~~~~
 173 option:--live[='DELAYUS']::
 174     Create the session in <<live-mode,live mode>>.
 175 +
 176 The optional 'DELAYUS' parameter, given in microseconds, is the
 177 maximum time the user can wait for the data to be flushed. This mode
 178 can be set with a network URL (options option:--set-url, or
 179 option:--ctrl-url and option:--data-url) and must have a relay
 180 daemon listening (see man:lttng-relayd(8)).
 181 +
 182 By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
 183 is set to `net://127.0.0.1`.
 184
 185 option:--snapshot::
 186     Create the session in <<snapshot-mode,snapshot mode>>.
 187     This is the equivalent of using the option:--no-output option and
 188     creating all the channels of this new tracing session in overwrite
 189     mode with an `mmap` output type.
 190
 191
 192 Output
 193 ~~~~~~
 194 option:--no-output::
 195     In <<local-mode,local mode>>, do not output any trace data.
 196
 197 option:-o 'PATH', option:--output='PATH'::
 198     In <<local-mode,local mode>>, set trace output path to 'PATH'.
 199
 200 option:--shm-path='PATH'::
 201     Create shared memory holding buffers at 'PATH'.
 202
 203
 204 URL
 205 ~~~
 206 See the <<url-format,URL format>> section above for more information
 207 about the syntax of the following options' 'URL' argument.
 208
 209 option:-C 'URL', option:--ctrl-url='URL'::
 210     Set control path URL to 'URL' (must use option:--data-url option
 211     also).
 212
 213 option:-D 'URL', option:--data-url='URL'::
 214     Set data path URL to 'URL' (must use option:--ctrl-url option
 215     also).
 216
 217 option:-U 'URL', option:--set-url='URL'::
 218     Set URL destination of the trace data to 'URL'. It is persistent for
 219     the session lifetime. This option sets both data
 220     (option:--data-url option) and control (option:--ctrl-url option)
 221     URLs at the same time.
 222 +
 223 In <<local-mode,local>> mode, 'URL' must start with `file://` followed
 224 by the destination path on the local file system.
 225
 226
 227 include::common-cmd-help-options.txt[]
 228
 229
 230 include::common-cmd-footer.txt[]
 231
 232
 233 SEE ALSO
 234 --------
 235 man:lttng-destroy(1),
 236 man:lttng-set-session(1),
 237 man:lttng(1)