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* ['SESSION'] [option:--shm-path='PATH']
  16       [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH']
  17
  18 Network streaming mode:
  19
  20 [verse]
  21 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='PATH']
  22       (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
  23
  24 Snapshot mode:
  25
  26 [verse]
  27 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot
  28       [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
  29
  30 Live mode:
  31
  32 [verse]
  33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
  34       [option:--shm-path='PATH'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
  35
  36 DESCRIPTION
  37 -----------
  38 The `lttng create` command creates a new tracing session.
  39
  40 A tracing session is a named container of channels, which in turn
  41 contain event rules. It is domain-agnostic, in that channels and event
  42 rules can be enabled for the user space tracer and/or the Linux
  43 kernel tracer.
  44
  45 On execution, an `.lttngrc` file is created, if it does not exist, in the
  46 user's home directory. This file contains the name of the current tracing
  47 session. When creating a new tracing session with `lttng create`, the
  48 current tracing session is set to this new tracing session. The
  49 man:lttng-set-session(1) command can be used to set the current
  50 tracing session without manually editing the `.lttngrc` file.
  51
  52 If 'SESSION' is omitted, a session name is automatically created having
  53 this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
  54 character `/`.
  55
  56 The option:--shm-path option can be used to specify the path to the
  57 shared memory holding the ring buffers. Specifying a location on an
  58 NVRAM file system makes it possible to retrieve the latest recorded
  59 trace data when the system reboots after a crash. To view the events
  60 of ring buffer files after a system crash, use the
  61 man:lttng-crash(1) utility.
  62
  63 Tracing sessions are destroyed using the man:lttng-destroy(1)
  64 command.
  65
  66
  67 Creation modes
  68 ~~~~~~~~~~~~~~
  69 There are four tracing session modes:
  70
  71 [[local-mode]]Local mode::
  72     Traces the local system and writes the trace to the local
  73     file system. The option:--output option specifies the trace path.
  74     Using option:--set-url=file://'PATH' is the equivalent of using
  75     option:--output='PATH'. The file system output can be disabled using
  76     the option:--no-output option.
  77 +
  78 If none of the options mentioned above are used, then the trace is
  79 written locally in the `$LTTNG_HOME/lttng-traces` directory
  80 (`$LTTNG_HOME` defaults to `$HOME`).
  81
  82 [[network-streaming-mode]]Network streaming mode::
  83     Traces the local system and sends the trace over the network to
  84     a listening relay daemon (see man:lttng-relayd(8)).
  85     The option:--set-url, or option:--ctrl-url and option:--data-url
  86     options set the trace output destination (see the
  87     <<url-format,URL format>> section below).
  88
  89 [[snapshot-mode]]Snapshot mode::
  90     Traces the local system without writing the trace to the local file
  91     system (implicit option:--no-output option). Channels are automatically
  92     configured to be snapshot-ready on creation (see
  93     man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
  94     command is used to take snapshots of the current ring buffers.
  95     The option:--set-url, or option:--ctrl-url and option:--data-url
  96     options set the default snapshot output destination.
  97
  98 [[live-mode]]Live mode::
  99     Traces the local system, sending trace data to an LTTng relay daemon
 100     over the network (see man:lttng-relayd(8)). The
 101     option:--set-url, or option:--ctrl-url and option:--data-url options
 102     set the trace output destination. The live output URLs cannot use
 103     the `file://` protocol (see the <<url-format,URL format>>
 104     section below).
 105
 106
 107 [[url-format]]
 108 URL format
 109 ~~~~~~~~~~
 110 The option:--set-url, option:--ctrl-url, and option:--data-url options'
 111 arguments are URLs.
 112
 113 The format of those URLs is one of:
 114
 115 [verse]
 116 file://'TRACEPATH'
 117 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
 118
 119 The `file://` protocol targets the *local file system* and can only
 120 be used as the option:--set-url option's argument when the session is
 121 created in <<local-mode,local>> or <<snapshot-mode,snapshot>> mode.
 122
 123 'TRACEPATH'::
 124     Absolute path to trace files on the local file system.
 125
 126 The other version is available when the session is created in
 127 <<network-streaming-mode,network streaming>>,
 128 <<snapshot-mode,snapshot>>, or <<live-mode,live>> mode.
 129
 130 'NETPROTO'::
 131     Network protocol, amongst:
 132 +
 133 --
 134 `net`::
 135     TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
 136     are respectively {default_network_control_port} and
 137     {default_network_data_port}.
 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 'PATH', 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 'URL', option:--ctrl-url='URL'::
 209     Set control path URL to 'URL' (must use option:--data-url option
 210     also).
 211
 212 option:-D 'URL', option:--data-url='URL'::
 213     Set data path URL to 'URL' (must use option:--ctrl-url option
 214     also).
 215
 216 option:-U 'URL', 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)