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