doc/man/lttng-create.1.txt

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