doc/man/lttng-create.1.txt

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