doc/man/lttng-create.1.txt

   1 lttng-create(1)
   2 ===============
   3 :revdate: 12 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:
  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 tracing session (see
  92 man:lttng-concepts(7) to learn more) to the created tracing session.
  93
  94 Show the status of the current tracing session with the
  95 man:lttng-status(1) command.
  96
  97 List the tracing sessions of your Unix user, or of all users if
  98 your Unix user is `root`, within the connected session daemon with the
  99 man:lttng-list(1) command.
 100
 101 Start and stop a tracing session with the man:lttng-start(1) and
 102 man:lttng-stop(1) commands.
 103
 104 Save and load a tracing session with the man:lttng-save(1) and
 105 man:lttng-load(1) commands.
 106
 107 Allow and disallow specific processes to record events with the
 108 man:lttng-track(1) and man:lttng-untrack(1) commands.
 109
 110 Archive the current trace chunk of (rotate) a tracing session with the
 111 man:lttng-rotate(1) command.
 112
 113 Destroy a tracing session with the man:lttng-destroy(1) command.
 114
 115
 116 [[modes]]
 117 Tracing session modes
 118 ~~~~~~~~~~~~~~~~~~~~~
 119 As documented in man:lttng-concepts(7), LTTng offers four tracing
 120 session modes:
 121
 122 [[local-mode]]Local mode::
 123     Write the trace data to the local file system.
 124 +
 125 The trace data output directory is:
 126 +
 127 With the option:--no-output option:::
 128     None: the file system output is disabled.
 129
 130 With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
 131     The directory 'DIR'.
 132
 133 Otherwise:::
 134     A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
 135     defaults to `$HOME`) directory, of which the name contains the
 136     tracing session name and the date/time.
 137
 138 [[network-streaming-mode]]Network streaming mode::
 139     Send the trace data over the network to a listening relay daemon
 140     (see man:lttng-relayd(8)).
 141 +
 142 Set the trace output destination with the option:--set-url option, or
 143 with the option:--ctrl-url and option:--data-url options (see the
 144 <<url-format,URL format>> section below).
 145
 146 [[snapshot-mode]]Snapshot mode (option:--snapshot option)::
 147     Only write the trace data to the local file system or send it to a
 148     listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
 149     snapshot (see the man:lttng-snapshot(1) command).
 150 +
 151 With this mode, LTTng:
 152 +
 153 With the option:--no-output option:::
 154     Does :not: add any snapshot output to the created tracing
 155     session.
 156
 157 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
 158     Adds a snapshot output named `snapshot-1` using the provided
 159     path or URL(s) to the created tracing session.
 160
 161 Otherwise:::
 162     Adds an automatic snapshot output named `snapshot-1` to the created
 163     tracing session.
 164 +
 165 The automatic snapshot output is a subdirectory, under the
 166 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
 167 directory, of which the name contains the tracing session name and the
 168 date/time.
 169
 170 [[live-mode]]Live mode (option:--live option)::
 171     Send the trace data over the network to a listening relay daemon
 172     (see man:lttng-relayd(8)) for live reading.
 173 +
 174 Set the trace output destination with the option:--set-url='URL' option,
 175 or with the option:--ctrl-url='URL' and option:--data-url='URL' options
 176 (see the <<url-format,URL format>> section below). 'URL' may :not: start
 177 with `file://`.
 178
 179
 180 [[url-format]]
 181 URL format
 182 ~~~~~~~~~~
 183 The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
 184 option:--data-url='URL' options is an URL.
 185
 186 There are two available 'URL' formats.
 187
 188 Local format::
 189 +
 190 [verse]
 191 file://'TRACEDIR'
 192 {nbsp}
 193 +
 194 The `file://` protocol targets the *local file system*: you may only use
 195 such an URL with the option:--set-url option when you create the tracing
 196 session in local or snapshot mode (see the <<modes,Tracing session
 197 modes>> section above).
 198 +
 199 'TRACEDIR':::
 200     Absolute path to the directory containing the trace data on the
 201     local file system.
 202
 203 Network format::
 204 +
 205 [verse]
 206 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
 207 {nbsp}
 208 +
 209 This format is only available when you create the tracing session in
 210 network streaming, snapshot (option:--snapshot), or live (option:--live)
 211 mode (see the <<modes,Tracing session modes>> section above).
 212 +
 213 'NETPROTO':::
 214     Network protocol, amongst:
 215 +
 216 --
 217 `net`::
 218     TCP over IPv4.
 219 +
 220 The default values of 'CTRLPORT' and 'DATAPORT'
 221 are respectively {default_network_control_port} and
 222 {default_network_data_port}.
 223
 224 `net6`::
 225     TCP over IPv6.
 226 +
 227 The default values of 'CTRLPORT' and 'DATAPORT'
 228 are respectively {default_network_control_port} and
 229 {default_network_data_port}.
 230
 231 `tcp`::
 232     Same as the `net` protocol.
 233 +
 234 You may only use this with the option:--ctrl-url and option:--data-url
 235 options together.
 236
 237 `tcp6`::
 238     Same as the `net6` protocol.
 239 +
 240 You can only be use this with the option:--ctrl-url and
 241 option:--data-url options together.
 242 --
 243 +
 244 ('HOST' | 'IPADDR'):::
 245     Hostname or IP address.
 246 +
 247 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
 248 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
 249
 250 'CTRLPORT':::
 251     Control TCP port.
 252
 253 'DATAPORT':::
 254     Data TCP port.
 255
 256 'TRACEDIR':::
 257     Path of the directory containing the trace data on the remote file
 258     system.
 259 +
 260 This path is relative to the base output directory of the LTTng relay
 261 daemon (see the nloption:--output option of man:lttng-relayd(8)).
 262
 263
 264 include::common-lttng-cmd-options-head.txt[]
 265
 266
 267 Mode selection
 268 ~~~~~~~~~~~~~~
 269 See the <<modes,Tracing session modes>> section above.
 270
 271 At most one of:
 272
 273 option:--live[='DELAYUS']::
 274     Create the tracing session in live mode.
 275 +
 276 The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
 277 for the data to be flushed (sent to the connected LTTng relay daemon).
 278 The default value of 'DELAYUS' is {default_lttng_live_timer}.
 279 +
 280 Set the URL of the relay daemon to connect to with the option:--set-url
 281 option, or with the option:--ctrl-url and option:--data-url options,
 282 instead of using `net://127.0.0.1`.
 283 +
 284 The session daemon must be able to connect to a listening relay daemon
 285 (see man:lttng-relayd(8)).
 286
 287 option:--snapshot::
 288     Create the tracing session in snapshot mode.
 289 +
 290 This is equivalent to:
 291 +
 292 * One of:
 293 +
 294 --
 295 With the option:--no-output option::
 296     Not adding any snapshot output after LTTng creates the tracing
 297     session.
 298
 299 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
 300     Adding a snapshot output named `snapshot-1` using the provided path
 301     or URL(s) immediately after LTTng creates the tracing session.
 302
 303 Otherwise::
 304     Adding an automatic snapshot output named `snapshot-1` immediately
 305     after LTTng creates the tracing session.
 306 +
 307 The automatic snapshot output is a subdirectory, under the
 308 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
 309 directory, of which the name contains the tracing session name and the
 310 date/time.
 311 --
 312
 313 * Forcing all the channels to be created for the tracing session to be
 314   configured with the nloption:--override and nloption:--output=++mmap++
 315   options (see man:lttng-enable-channel(1)).
 316
 317
 318 Output
 319 ~~~~~~
 320 option:--no-output::
 321     Depending on the tracing session mode (see the <<modes,Tracing
 322     session modes>> section above):
 323 +
 324 Local mode:::
 325     Disable the file system output.
 326
 327 Snapshot mode (option:--snapshot option):::
 328     Do :not: add a snapshot output after creating the tracing session.
 329
 330 option:-o 'DIR', option:--output='DIR'::
 331     Equivalent to option:--set-url=++file://++__DIR__.
 332
 333 option:--shm-path='DIR'::
 334     Set the path of the directory containing the shared memory files
 335     holding the channel ring buffers to 'DIR' on the local file sytem.
 336
 337
 338 URL
 339 ~~~
 340 See the <<url-format,URL format>> section above to learn more about the
 341 syntax of the 'URL' argument of the following options.
 342
 343 option:-C 'URL', option:--ctrl-url='URL'::
 344     Set the control path URL to 'URL'.
 345 +
 346 You must also use the option:--data-url option.
 347 +
 348 Not available in local mode (see the <<modes,Tracing session modes>>
 349 section above).
 350 +
 351 In snapshot mode, this is equivalent to using the nloption:--ctrl-url
 352 option of the `add-output` action of the man:lttng-snapshot(1) command
 353 immediately after creating the tracing session.
 354
 355 option:-D 'URL', option:--data-url='URL'::
 356     Set the trace data path URL to 'URL'.
 357 +
 358 You must also use the option:--ctrl-url option.
 359 +
 360 Not available in local mode (see the <<modes,Tracing session modes>>
 361 section above).
 362 +
 363 In snapshot mode, this is equivalent to using the nloption:--data-url
 364 option of the `add-output` action of the man:lttng-snapshot(1) command
 365 immediately after creating the tracing session.
 366
 367 option:-U 'URL', option:--set-url='URL'::
 368     Set the destination URL of the control path and trace data to 'URL'.
 369 +
 370 This URL remains unchanged as long as the tracing session exists.
 371 +
 372 Depending on the tracing session mode (see the <<modes,Tracing session
 373 modes>> section above):
 374 +
 375 Local mode:::
 376     'URL' must start with `file://`, followed with the destination
 377     directory path on the local file system.
 378
 379 Network streaming and live modes:::
 380     Equivalent to using both the option:--ctrl-url and option:--data-url
 381     options.
 382
 383 Snapshot mode (option:--snapshot option):::
 384     Equivalent to using the 'URL' non-option argument of the
 385     `add-output` action of the man:lttng-snapshot(1) command immediately
 386     after creating the tracing session.
 387
 388
 389 include::common-lttng-cmd-help-options.txt[]
 390
 391
 392 include::common-lttng-cmd-after-options.txt[]
 393
 394
 395 include::common-footer.txt[]
 396
 397
 398 SEE ALSO
 399 --------
 400 man:lttng(1),
 401 man:lttng-destroy(1),
 402 man:lttng-enable-channel(1),
 403 man:lttng-list(1),
 404 man:lttng-rotate(1),
 405 man:lttng-save(1),
 406 man:lttng-set-session(1),
 407 man:lttng-start(1),
 408 man:lttng-status(1),
 409 man:lttng-track(1),
 410 man:lttng-concepts(7),
 411 man:lttng-relayd(8),
 412 man:lttng-sessiond(8)