doc/man/lttng-create.1.txt

   1 lttng-create(1)
   2 ===============
   3 :revdate: 3 May 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-create - Create an LTTng tracing session
   9
  10
  11 SYNOPSIS
  12 --------
  13 Create a local mode tracing session:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
  17       [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
  18
  19 Create a network streaming mode tracing session:
  20
  21 [verse]
  22 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
  23       (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
  24
  25 Create a snapshot mode tracing session:
  26
  27 [verse]
  28 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot [option:--shm-path='DIR']
  29       [option:--no-output | option:--output='DIR' | option:--set-url='URL' |
  30        option:--ctrl-url='URL' option:--data-url='URL']
  31
  32 Create a live mode tracing session:
  33
  34 [verse]
  35 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
  36       [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
  37
  38 DESCRIPTION
  39 -----------
  40 The `lttng create` command creates a new tracing session for your Unix
  41 user within the connected session daemon (see the ``Session daemon
  42 connection'' section of man:lttng(1) to learn how a user application
  43 connects to a session daemon).
  44
  45 See man:lttng-concepts(7) to learn more about tracing sessions.
  46
  47 Without the 'SESSION' argument, LTTng automatically generates a tracing
  48 session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
  49 'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may
  50 :not: contain the character `/`.
  51
  52 Specify the path of the directory containing the shared memory files
  53 holding the channel ring buffers with the option:--shm-path option.
  54 Specifying a location on an NVRAM file system makes it possible to
  55 recover the latest recorded trace data when the system reboots after a
  56 crash with the man:lttng-crash(1) utility.
  57
  58 By default, the `create` command automatically spawns a session daemon
  59 for your Unix user if none is currently running. Override the path of
  60 the session daemon binary to spawn with the general
  61 genoption:--sessiond-path option. Avoid automatically spawning a session
  62 daemon with the general genoption:--no-sessiond option.
  63
  64 On success, the `create` command sets the current tracing session (see
  65 man:lttng-concepts(7) to learn more) to the created tracing session.
  66
  67 Show the status of the current tracing session with the
  68 man:lttng-status(1) command.
  69
  70 List the tracing sessions of your Unix user, or of all users if
  71 your Unix user is `root`, within the connected session daemon with the
  72 man:lttng-list(1) command.
  73
  74 Start and stop a tracing session with the man:lttng-start(1) and
  75 man:lttng-stop(1) commands.
  76
  77 Save and load a tracing session with the man:lttng-save(1) and
  78 man:lttng-load(1) commands.
  79
  80 Allow and disallow specific processes to record events with the
  81 man:lttng-track(1) and man:lttng-untrack(1) commands.
  82
  83 Archive the current trace chunk of (rotate) a tracing session with the
  84 man:lttng-rotate(1) command.
  85
  86 Destroy a tracing session with the man:lttng-destroy(1) command.
  87
  88
  89 [[modes]]
  90 Tracing session modes
  91 ~~~~~~~~~~~~~~~~~~~~~
  92 As documented in man:lttng-concepts(7), LTTng offers four tracing
  93 session modes:
  94
  95 [[local-mode]]Local mode::
  96     Write the trace data to the local file system.
  97 +
  98 The trace data output directory is:
  99 +
 100 With the option:--no-output option:::
 101     None: the file system output is disabled.
 102
 103 With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
 104     The directory 'DIR'.
 105
 106 Otherwise:::
 107     A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
 108     defaults to `$HOME`) directory, of which the name contains the
 109     tracing session name and the date/time.
 110
 111 [[network-streaming-mode]]Network streaming mode::
 112     Send the trace data over the network to a listening relay daemon
 113     (see man:lttng-relayd(8)).
 114 +
 115 Set the trace output destination with the option:--set-url option, or
 116 with the option:--ctrl-url and option:--data-url options (see the
 117 <<url-format,URL format>> section below).
 118
 119 [[snapshot-mode]]Snapshot mode (option:--snapshot option)::
 120     Only write the trace data to the local file system or send it to a
 121     listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
 122     snapshot (see the man:lttng-snapshot(1) command).
 123 +
 124 With this mode, LTTng:
 125 +
 126 With the option:--no-output option:::
 127     Does :not: add any snapshot output to the created tracing
 128     session.
 129
 130 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
 131     Adds a snapshot output named `snapshot-1` using the provided
 132     path or URL(s) to the created tracing session.
 133
 134 Otherwise:::
 135     Adds an automatic snapshot output named `snapshot-1` to the created
 136     tracing session.
 137 +
 138 The automatic snapshot output is a subdirectory, under the
 139 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
 140 directory, of which the name contains the tracing session name and the
 141 date/time.
 142
 143 [[live-mode]]Live mode (option:--live option)::
 144     Send the trace data over the network to a listening relay daemon
 145     (see man:lttng-relayd(8)) for live reading.
 146 +
 147 Set the trace output destination with the option:--set-url='URL' option,
 148 or with the option:--ctrl-url='URL' and option:--data-url='URL' options
 149 (see the <<url-format,URL format>> section below). 'URL' may :not: start
 150 with `file://`.
 151
 152
 153 [[url-format]]
 154 URL format
 155 ~~~~~~~~~~
 156 The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
 157 option:--data-url='URL' options is an URL.
 158
 159 There are two available 'URL' formats.
 160
 161 Local format::
 162 +
 163 [verse]
 164 file://'TRACEDIR'
 165 {nbsp}
 166 +
 167 The `file://` protocol targets the *local file system*: you may only use
 168 such an URL with the option:--set-url option when you create the tracing
 169 session in local or snapshot mode (see the <<modes,Tracing session
 170 modes>> section above).
 171 +
 172 'TRACEDIR':::
 173     Absolute path to the directory containing the trace data on the
 174     local file system.
 175
 176 Network format::
 177 +
 178 [verse]
 179 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
 180 {nbsp}
 181 +
 182 This format is only available when you create the tracing session in
 183 network streaming, snapshot (option:--snapshot), or live (option:--live)
 184 mode (see the <<modes,Tracing session modes>> section above).
 185 +
 186 'NETPROTO':::
 187     Network protocol, amongst:
 188 +
 189 --
 190 `net`::
 191     TCP over IPv4.
 192 +
 193 The default values of 'CTRLPORT' and 'DATAPORT'
 194 are respectively {default_network_control_port} and
 195 {default_network_data_port}.
 196
 197 `net6`::
 198     TCP over IPv6.
 199 +
 200 The default values of 'CTRLPORT' and 'DATAPORT'
 201 are respectively {default_network_control_port} and
 202 {default_network_data_port}.
 203
 204 `tcp`::
 205     Same as the `net` protocol.
 206 +
 207 You may only use this with the option:--ctrl-url and option:--data-url
 208 options together.
 209
 210 `tcp6`::
 211     Same as the `net6` protocol.
 212 +
 213 You can only be use this with the option:--ctrl-url and
 214 option:--data-url options together.
 215 --
 216 +
 217 ('HOST' | 'IPADDR'):::
 218     Hostname or IP address.
 219 +
 220 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
 221 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
 222
 223 'CTRLPORT':::
 224     Control TCP port.
 225
 226 'DATAPORT':::
 227     Data TCP port.
 228
 229 'TRACEDIR':::
 230     Path of the directory containing the trace data on the remote file
 231     system.
 232 +
 233 This path is relative to the base output directory of the LTTng relay
 234 daemon (see the nloption:--output option of man:lttng-relayd(8)).
 235
 236
 237 include::common-lttng-cmd-options-head.txt[]
 238
 239
 240 Mode selection
 241 ~~~~~~~~~~~~~~
 242 See the <<modes,Tracing session modes>> section above.
 243
 244 At most one of:
 245
 246 option:--live[='DELAYUS']::
 247     Create the tracing session in live mode.
 248 +
 249 The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
 250 for the data to be flushed (sent to the connected LTTng relay daemon).
 251 The default value of 'DELAYUS' is {default_lttng_live_timer}.
 252 +
 253 Set the URL of the relay daemon to connect to with the option:--set-url
 254 option, or with the option:--ctrl-url and option:--data-url options,
 255 instead of using `net://127.0.0.1`.
 256 +
 257 The session daemon must be able to connect to a listening relay daemon
 258 (see man:lttng-relayd(8)).
 259
 260 option:--snapshot::
 261     Create the tracing session in snapshot mode.
 262 +
 263 This is equivalent to:
 264 +
 265 * One of:
 266 +
 267 --
 268 With the option:--no-output option::
 269     Not adding any snapshot output after LTTng creates the tracing
 270     session.
 271
 272 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
 273     Adding a snapshot output named `snapshot-1` using the provided path
 274     or URL(s) immediately after LTTng creates the tracing session.
 275
 276 Otherwise::
 277     Adding an automatic snapshot output named `snapshot-1` immediately
 278     after LTTng creates the tracing session.
 279 +
 280 The automatic snapshot output is a subdirectory, under the
 281 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
 282 directory, of which the name contains the tracing session name and the
 283 date/time.
 284 --
 285
 286 * Forcing all the channels to be created for the tracing session to be
 287   configured with the nloption:--override and nloption:--output=++mmap++
 288   options (see man:lttng-enable-channel(1)).
 289
 290
 291 Output
 292 ~~~~~~
 293 option:--no-output::
 294     Depending on the tracing session mode (see the <<modes,Tracing
 295     session modes>> section above):
 296 +
 297 Local mode:::
 298     Disable the file system output.
 299
 300 Snapshot mode (option:--snapshot option):::
 301     Do :not: add a snapshot output after creating the tracing session.
 302
 303 option:-o 'DIR', option:--output='DIR'::
 304     Equivalent to option:--set-url=++file://++__DIR__.
 305
 306 option:--shm-path='DIR'::
 307     Set the path of the directory containing the shared memory files
 308     holding the channel ring buffers to 'DIR' on the local file sytem.
 309
 310
 311 URL
 312 ~~~
 313 See the <<url-format,URL format>> section above to learn more about the
 314 syntax of the 'URL' argument of the following options.
 315
 316 option:-C 'URL', option:--ctrl-url='URL'::
 317     Set the control path URL to 'URL'.
 318 +
 319 You must also use the option:--data-url option.
 320 +
 321 Not available in local mode (see the <<modes,Tracing session modes>>
 322 section above).
 323 +
 324 In snapshot mode, this is equivalent to using the nloption:--ctrl-url
 325 option of the `add-output` action of the man:lttng-snapshot(1) command
 326 immediately after creating the tracing session.
 327
 328 option:-D 'URL', option:--data-url='URL'::
 329     Set the trace data path URL to 'URL'.
 330 +
 331 You must also use the option:--ctrl-url option.
 332 +
 333 Not available in local mode (see the <<modes,Tracing session modes>>
 334 section above).
 335 +
 336 In snapshot mode, this is equivalent to using the nloption:--data-url
 337 option of the `add-output` action of the man:lttng-snapshot(1) command
 338 immediately after creating the tracing session.
 339
 340 option:-U 'URL', option:--set-url='URL'::
 341     Set the destination URL of the control path and trace data to 'URL'.
 342 +
 343 This URL remains unchanged as long as the tracing session exists.
 344 +
 345 Depending on the tracing session mode (see the <<modes,Tracing session
 346 modes>> section above):
 347 +
 348 Local mode:::
 349     'URL' must start with `file://`, followed with the destination
 350     directory path on the local file system.
 351
 352 Network streaming and live modes:::
 353     Equivalent to using both the option:--ctrl-url and option:--data-url
 354     options.
 355
 356 Snapshot mode (option:--snapshot option):::
 357     Equivalent to using the 'URL' non-option argument of the
 358     `add-output` action of the man:lttng-snapshot(1) command immediately
 359     after creating the tracing session.
 360
 361
 362 include::common-lttng-cmd-help-options.txt[]
 363
 364
 365 include::common-lttng-cmd-after-options.txt[]
 366
 367
 368 include::common-footer.txt[]
 369
 370
 371 SEE ALSO
 372 --------
 373 man:lttng(1),
 374 man:lttng-destroy(1),
 375 man:lttng-enable-channel(1),
 376 man:lttng-list(1),
 377 man:lttng-rotate(1),
 378 man:lttng-save(1),
 379 man:lttng-set-session(1),
 380 man:lttng-start(1),
 381 man:lttng-status(1),
 382 man:lttng-track(1),
 383 man:lttng-concepts(7),
 384 man:lttng-relayd(8),
 385 man:lttng-sessiond(8)