doc/man/lttng-create.1.txt

   1 lttng-create(1)
   2 ===============
   3 :revdate: 7 December 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-create - Create an LTTng recording session
   9
  10
  11 SYNOPSIS
  12 --------
  13 Create a local mode recording 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 recording 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 recording 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 recording 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 recording 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 recording sessions.
  46
  47 Without the 'SESSION' argument, LTTng automatically generates a recording
  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. Note that, as of
  57 LTTng{nbsp}{lttng_version}, this feature is only available for user
  58 space channels.
  59
  60 By default, the `create` command automatically spawns:
  61
  62 * A session daemon for your Unix user if none is currently running.
  63 +
  64 Override the path of the session daemon binary to spawn with the
  65 general genoption:--sessiond-path option.
  66 +
  67 Avoid automatically spawning a session daemon with the general
  68 genoption:--no-sessiond option.
  69
  70 * A relay daemon (see man:lttng-relayd(8)) if all the following
  71   statements are true:
  72 +
  73 --
  74 * You specify the option:--live option.
  75
  76 * You don't specify any of the option:--set-url, option:--ctrl-url, or
  77   option:--data-url options.
  78
  79 * No relay daemon is currently listening for TCP connections on
  80   +127.0.0.1:{default_network_viewer_port}+ (default LTTng live reader
  81   connection address and port).
  82 --
  83 +
  84 In this case, the `create` command spawns a relay daemon as such:
  85 +
  86 [verse]
  87 *lttng-relayd* nloption:--live-port=**tcp://localhost:{default_network_viewer_port}**
  88 {nbsp}
  89 +
  90 Override the path of the relay daemon binary to spawn with the general
  91 genoption:--relayd-path option.
  92
  93 On success, the `create` command sets the current recording session (see
  94 man:lttng-concepts(7) to learn more) to the created recording session.
  95
  96 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  97
  98 Show the status of the current recording session with the
  99 man:lttng-status(1) command.
 100
 101 List the recording sessions of your Unix user, or of all users if
 102 your Unix user is `root`, within the connected session daemon with the
 103 man:lttng-list(1) command.
 104
 105 Start and stop a recording session with the man:lttng-start(1) and
 106 man:lttng-stop(1) commands.
 107
 108 Save and load a recording session with the man:lttng-save(1) and
 109 man:lttng-load(1) commands.
 110
 111 Allow and disallow specific processes to record events with the
 112 man:lttng-track(1) and man:lttng-untrack(1) commands.
 113
 114 Archive the current trace chunk of (rotate) a recording session with the
 115 man:lttng-rotate(1) command.
 116
 117 Destroy a recording session with the man:lttng-destroy(1) command.
 118
 119
 120 [[modes]]
 121 Recording session modes
 122 ~~~~~~~~~~~~~~~~~~~~~~~
 123 As documented in man:lttng-concepts(7), LTTng offers four recording
 124 session modes:
 125
 126 [[local-mode]]Local mode::
 127     Write the trace data to the local file system.
 128 +
 129 The trace data output directory is:
 130 +
 131 With the option:--no-output option:::
 132     None: the file system output is disabled.
 133
 134 With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
 135     The directory 'DIR'.
 136
 137 Otherwise:::
 138     A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
 139     defaults to `$HOME`) directory, of which the name contains the
 140     recording session name and the date/time.
 141
 142 [[network-streaming-mode]]Network streaming mode::
 143     Send the trace data over the network to a listening relay daemon
 144     (see man:lttng-relayd(8)).
 145 +
 146 Set the trace output destination with the option:--set-url option, or
 147 with the option:--ctrl-url and option:--data-url options (see the
 148 ``<<url-format,URL format>>'' section below).
 149
 150 [[snapshot-mode]]Snapshot mode (option:--snapshot option)::
 151     Only write the trace data to the local file system or send it to a
 152     listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
 153     snapshot (see the man:lttng-snapshot(1) command).
 154 +
 155 With this mode, LTTng:
 156 +
 157 With the option:--no-output option:::
 158     Does :not: add any snapshot output to the created recording
 159     session.
 160
 161 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
 162     Adds a snapshot output named `snapshot-1` using the provided
 163     path or URL(s) to the created recording session.
 164
 165 Otherwise:::
 166     Adds an automatic snapshot output named `snapshot-1` to the created
 167     recording session.
 168 +
 169 The automatic snapshot output is a subdirectory, under the
 170 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
 171 directory, of which the name contains the recording session name and the
 172 date/time.
 173
 174 [[live-mode]]Live mode (option:--live option)::
 175     Send the trace data over the network to a listening relay daemon
 176     (see man:lttng-relayd(8)) for live reading.
 177 +
 178 Set the trace output destination with the option:--set-url='URL' option,
 179 or with the option:--ctrl-url='URL' and option:--data-url='URL' options
 180 (see the ``<<url-format,URL format>>'' section below). 'URL' may :not:
 181 start with `file://`.
 182
 183
 184 [[url-format]]
 185 URL format
 186 ~~~~~~~~~~
 187 The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
 188 option:--data-url='URL' options is an URL.
 189
 190 There are two available 'URL' formats.
 191
 192 Local format::
 193 +
 194 [verse]
 195 file://'TRACEDIR'
 196 {nbsp}
 197 +
 198 The `file://` protocol targets the *local file system*: you may only use
 199 such an URL with the option:--set-url option when you create the
 200 recording session in local or snapshot mode (see the ``<<modes,Recording
 201 session modes>>'' section above).
 202 +
 203 'TRACEDIR':::
 204     Absolute path to the directory containing the trace data on the
 205     local file system.
 206
 207 Network format::
 208 +
 209 [verse]
 210 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
 211 {nbsp}
 212 +
 213 This format is only available when you create the recording session in
 214 network streaming, snapshot (option:--snapshot), or live (option:--live)
 215 mode (see the ``<<modes,Recording session modes>>'' section above).
 216 +
 217 'NETPROTO':::
 218     Network protocol, amongst:
 219 +
 220 --
 221 `net`::
 222     TCP over IPv4.
 223 +
 224 The default values of 'CTRLPORT' and 'DATAPORT'
 225 are respectively {default_network_control_port} and
 226 {default_network_data_port}.
 227
 228 `net6`::
 229     TCP over IPv6.
 230 +
 231 The default values of 'CTRLPORT' and 'DATAPORT'
 232 are respectively {default_network_control_port} and
 233 {default_network_data_port}.
 234
 235 `tcp`::
 236     Same as the `net` protocol.
 237 +
 238 You may only use this with the option:--ctrl-url and option:--data-url
 239 options together.
 240
 241 `tcp6`::
 242     Same as the `net6` protocol.
 243 +
 244 You can only be use this with the option:--ctrl-url and
 245 option:--data-url options together.
 246 --
 247 +
 248 ('HOST' | 'IPADDR'):::
 249     Hostname or IP address.
 250 +
 251 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
 252 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
 253
 254 'CTRLPORT':::
 255     Control TCP port.
 256
 257 'DATAPORT':::
 258     Data TCP port.
 259
 260 'TRACEDIR':::
 261     Path of the directory containing the trace data on the remote file
 262     system.
 263 +
 264 This path is relative to the base output directory of the LTTng relay
 265 daemon (see the nloption:--output option of man:lttng-relayd(8)).
 266
 267
 268 include::common-lttng-cmd-options-head.txt[]
 269
 270
 271 Mode selection
 272 ~~~~~~~~~~~~~~
 273 See the ``<<modes,Recording session modes>>'' section above.
 274
 275 At most one of:
 276
 277 option:--live[='DELAYUS']::
 278     Create the recording session in live mode.
 279 +
 280 The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
 281 for the data to be flushed (sent to the connected LTTng relay daemon).
 282 The default value of 'DELAYUS' is {default_lttng_live_timer}.
 283 +
 284 Set the URL of the relay daemon to connect to with the option:--set-url
 285 option, or with the option:--ctrl-url and option:--data-url options,
 286 instead of using `net://127.0.0.1`.
 287 +
 288 The session daemon must be able to connect to a listening relay daemon
 289 (see man:lttng-relayd(8)).
 290
 291 option:--snapshot::
 292     Create the recording session in snapshot mode.
 293 +
 294 This is equivalent to:
 295 +
 296 * One of:
 297 +
 298 --
 299 With the option:--no-output option::
 300     Not adding any snapshot output after LTTng creates the recording
 301     session.
 302
 303 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
 304     Adding a snapshot output named `snapshot-1` using the provided path
 305     or URL(s) immediately after LTTng creates the recording session.
 306
 307 Otherwise::
 308     Adding an automatic snapshot output named `snapshot-1` immediately
 309     after LTTng creates the recording session.
 310 +
 311 The automatic snapshot output is a subdirectory, under the
 312 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
 313 directory, of which the name contains the recording session name and the
 314 date/time.
 315 --
 316
 317 * Forcing all the channels to be created for the recording session to be
 318   configured with the nloption:--override and nloption:--output=++mmap++
 319   options (see man:lttng-enable-channel(1)).
 320
 321
 322 Output
 323 ~~~~~~
 324 option:--no-output::
 325     Depending on the recording session mode (see the ``<<modes,Recording
 326     session modes>>'' section above):
 327 +
 328 Local mode:::
 329     Disable the file system output.
 330
 331 Snapshot mode (option:--snapshot option):::
 332     Do :not: add a snapshot output after creating the recording session.
 333
 334 option:-o 'DIR', option:--output='DIR'::
 335     Equivalent to option:--set-url=++file://++__DIR__.
 336
 337 option:--shm-path='DIR'::
 338     Set the path of the directory containing the shared memory files
 339     holding the channel ring buffers to 'DIR' on the local file sytem.
 340 +
 341 NOTE: As of LTTng{nbsp}{lttng_version}, LTTng only considers this option
 342 for user space (including Java and Python) channels, but this may change
 343 in the future.
 344
 345
 346 URL
 347 ~~~
 348 See the ``<<url-format,URL format>>'' section above to learn more about
 349 the syntax of the 'URL' argument of the following options.
 350
 351 option:-C 'URL', option:--ctrl-url='URL'::
 352     Set the control path URL to 'URL'.
 353 +
 354 You must also use the option:--data-url option.
 355 +
 356 Not available in local mode (see the ``<<modes,Recording session
 357 modes>>'' section above).
 358 +
 359 In snapshot mode, this is equivalent to using the nloption:--ctrl-url
 360 option of the `add-output` action of the man:lttng-snapshot(1) command
 361 immediately after creating the recording session.
 362
 363 option:-D 'URL', option:--data-url='URL'::
 364     Set the trace data path URL to 'URL'.
 365 +
 366 You must also use the option:--ctrl-url option.
 367 +
 368 Not available in local mode (see the ``<<modes,Recording session
 369 modes>>'' section above).
 370 +
 371 In snapshot mode, this is equivalent to using the nloption:--data-url
 372 option of the `add-output` action of the man:lttng-snapshot(1) command
 373 immediately after creating the recording session.
 374
 375 option:-U 'URL', option:--set-url='URL'::
 376     Set the destination URL of the control path and trace data to 'URL'.
 377 +
 378 This URL remains unchanged as long as the recording session exists.
 379 +
 380 Depending on the recording session mode (see the ``<<modes,Recording
 381 session modes>>'' section above):
 382 +
 383 Local mode:::
 384     'URL' must start with `file://`, followed with the destination
 385     directory path on the local file system.
 386
 387 Network streaming and live modes:::
 388     Equivalent to using both the option:--ctrl-url and option:--data-url
 389     options.
 390
 391 Snapshot mode (option:--snapshot option):::
 392     Equivalent to using the 'URL' non-option argument of the
 393     `add-output` action of the man:lttng-snapshot(1) command immediately
 394     after creating the recording session.
 395
 396
 397 include::common-lttng-cmd-help-options.txt[]
 398
 399
 400 include::common-lttng-cmd-after-options.txt[]
 401
 402
 403 [[examples]]
 404 EXAMPLES
 405 --------
 406 .Create a normal mode recording session with a generated name.
 407 ====
 408 [role="term"]
 409 ----
 410 $ lttng create
 411 ----
 412 ====
 413
 414 .Create a normal mode recording session with a custom name.
 415 ====
 416 [role="term"]
 417 ----
 418 $ lttng create my-session
 419 ----
 420 ====
 421
 422 .Create a normal mode recording session with a specific output directory.
 423 ====
 424 See the option:--output option.
 425
 426 [role="term"]
 427 ----
 428 $ lttng create --output=/path/to/traces
 429 ----
 430 ====
 431
 432 .Create a network streaming mode recording session.
 433 ====
 434 See the ``Output directory'' section of man:lttng-relayd(8) to
 435 understand where the relay daemon to connect to (`10.0.0.242`) writes
 436 the received traces.
 437
 438 See the option:--set-url option.
 439
 440 [role="term"]
 441 ----
 442 $ lttng create --set-url=net://10.0.0.242/inv4
 443 ----
 444 ====
 445
 446 .Create a snapshot mode recording session with a default snapshot output.
 447 ====
 448 See the option:--snapshot option.
 449
 450 [role="term"]
 451 ----
 452 $ lttng create --snapshot
 453 ----
 454 ====
 455
 456 .Create a snapshot mode recording session with a custom snapshot output.
 457 ====
 458 See the option:--snapshot and option:--set-url options.
 459
 460 [role="term"]
 461 ----
 462 $ lttng create --snapshot \
 463         --set-url=tcp://192.168.1.102:1234:5678/my-snapshots
 464 ----
 465 ====
 466
 467 .Create a snapshot mode recording session with no snapshot output.
 468 ====
 469 See the option:--snapshot and option:--no-output options.
 470
 471 [role="term"]
 472 ----
 473 $ lttng create --snapshot --no-output
 474 ----
 475 ====
 476
 477 .Create an LTTng live mode recording session with a default relay daemon URL.
 478 ====
 479 See the option:--live option.
 480
 481 [role="term"]
 482 ----
 483 $ lttng create --live
 484 ----
 485 ====
 486
 487 .Create an LTTng live mode recording session with a custom live timer period and relay daemon URL.
 488 ====
 489 See the option:--live and option:--set-url options.
 490
 491 [role="term"]
 492 ----
 493 $ lttng create --live=250000 \
 494                --set-url=tcp://relayd34:4885:4886
 495 ----
 496 ====
 497
 498 .Create a normal mode recording session with a custom directory containing the ring buffer shared memory files.
 499 ====
 500 See the option:--shm-path option.
 501
 502 [role="term"]
 503 ----
 504 $ lttng create my-session --shm-path=/mnt/nvram2/lttng
 505 ----
 506 ====
 507
 508
 509 include::common-footer.txt[]
 510
 511
 512 SEE ALSO
 513 --------
 514 man:lttng(1),
 515 man:lttng-destroy(1),
 516 man:lttng-enable-channel(1),
 517 man:lttng-list(1),
 518 man:lttng-rotate(1),
 519 man:lttng-save(1),
 520 man:lttng-set-session(1),
 521 man:lttng-start(1),
 522 man:lttng-status(1),
 523 man:lttng-track(1),
 524 man:lttng-concepts(7),
 525 man:lttng-relayd(8),
 526 man:lttng-sessiond(8)