doc/man/lttng-enable-channel.1.txt

   1 lttng-enable-channel(1)
   2 =======================
   3
   4
   5 NAME
   6 ----
   7 lttng-enable-channel - Create or enable LTTng channels
   8
   9
  10 SYNOPSIS
  11 --------
  12 Create a Linux kernel channel:
  13
  14 [verse]
  15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
  16       [option:--overwrite] [option:--output=(`mmap` | `splice`)]
  17       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
  18       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
  19       [option:--monitor-timer='PERIODUS']
  20       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
  21       [option:--session='SESSION'] 'CHANNEL'
  22
  23 Create a user space channel:
  24
  25 [verse]
  26 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
  27       [option:--overwrite] [option:--buffers-pid]
  28       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
  29       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
  30       [option:--monitor-timer='PERIODUS'] [option:--blocking-timeout='TIMEOUTUS']
  31       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
  32       [option:--session='SESSION'] 'CHANNEL'
  33
  34 Enable existing channel(s):
  35
  36 [verse]
  37 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
  38       [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
  39
  40
  41 DESCRIPTION
  42 -----------
  43 The `lttng enable-channel` command can create a new channel, or enable
  44 one or more existing and disabled ones.
  45
  46 A channel is the owner of sub-buffers holding recorded events. Event,
  47 rules, when created using man:lttng-enable-event(1), are always
  48 assigned to a channel. When creating a new channel, many parameters
  49 related to those sub-buffers can be fine-tuned. They are described in
  50 the subsections below.
  51
  52 When 'CHANNEL' does not name an existing channel, a channel named
  53 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
  54 is enabled.
  55
  56 Note that the man:lttng-enable-event(1) command can automatically
  57 create default channels when no channel exist.
  58
  59 A channel is always contained in a tracing session
  60 (see man:lttng-create(1) for creating a tracing session). The
  61 session in which a channel is created using `lttng enable-channel` can
  62 be specified using the option:--session option. If the option:--session
  63 option is omitted, the current tracing session is targeted.
  64
  65 Existing enabled channels can be disabled using
  66 man:lttng-disable-channel(1). Channels of a given session can be
  67 listed using man:lttng-list(1).
  68
  69 See the <<limitations,LIMITATIONS>> section below for a list of
  70 limitations of this command to consider.
  71
  72
  73 Event loss modes
  74 ~~~~~~~~~~~~~~~~
  75 LTTng tracers are non-blocking: when no empty sub-buffer exists,
  76 losing events is acceptable when the alternative would be to cause
  77 substantial delays in the instrumented application's execution.
  78
  79 LTTng privileges performance over integrity, aiming at perturbing the
  80 traced system as little as possible in order to make tracing of subtle
  81 race conditions and rare interrupt cascades possible.
  82
  83 When it comes to losing events because no empty sub-buffer is available,
  84 the channel's event loss mode, specified by one of the option:--discard
  85 and option:--overwrite options, determines what to do amongst:
  86
  87 Discard::
  88     Drop the newest events until a sub-buffer is released.
  89
  90 Overwrite::
  91     Clear the sub-buffer containing the oldest recorded events and start
  92     recording the newest events there. This mode is sometimes called
  93     _flight recorder mode_ because it behaves like a flight recorder:
  94     always keep a fixed amount of the latest data.
  95
  96 Which mechanism to choose depends on the context: prioritize the newest
  97 or the oldest events in the ring buffer?
  98
  99 Beware that, in overwrite mode (option:--overwrite option), a whole
 100 sub-buffer is abandoned as soon as a new event doesn't find an empty
 101 sub-buffer, whereas in discard mode (option:--discard option), only the
 102 event that doesn't fit is discarded.
 103
 104 Also note that a count of lost events is incremented and saved in the
 105 trace itself when an event is lost in discard mode, whereas no
 106 information is kept when a sub-buffer gets overwritten before being
 107 committed.
 108
 109 The probability of losing events, if it is experience in a given
 110 context, can be reduced by fine-tuning the sub-buffers count and size
 111 (see next subsection).
 112
 113
 114 Sub-buffers count and size
 115 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 116 The option:--num-subbuf and option:--subbuf-size options respectively
 117 set the number of sub-buffers and their individual size when creating
 118 a new channel.
 119
 120 Note that there is a noticeable tracer's CPU overhead introduced when
 121 switching sub-buffers (marking a full one as consumable and switching
 122 to an empty one for the following events to be recorded). Knowing this,
 123 the following list presents a few practical situations along with how
 124 to configure sub-buffers for them when creating a channel in overwrite
 125 mode (option:--overwrite option):
 126
 127 High event throughput::
 128     In general, prefer bigger sub-buffers to lower the risk of losing
 129     events. Having bigger sub-buffers also ensures a lower sub-buffer
 130     switching frequency. The number of sub-buffers is only meaningful
 131     if the channel is enabled in overwrite mode: in this case, if a
 132     sub-buffer overwrite happens, the other sub-buffers
 133     are left unaltered.
 134
 135 Low event throughput::
 136     In general, prefer smaller sub-buffers since the risk of losing
 137     events is already low. Since events happen less frequently, the
 138     sub-buffer switching frequency should remain low and thus the
 139     tracer's overhead should not be a problem.
 140
 141 Low memory system::
 142     If the target system has a low memory limit, prefer fewer first,
 143     then smaller sub-buffers. Even if the system is limited in memory,
 144     it is recommended to keep the sub-buffers as big as possible to
 145     avoid a high sub-buffer switching frequency.
 146
 147 In discard mode (option:--discard option), the sub-buffers count
 148 parameter is pointless: using two sub-buffers and setting their size
 149 according to the requirements of the context is fine.
 150
 151
 152 Switch timer
 153 ~~~~~~~~~~~~
 154 When a channel's switch timer fires, a sub-buffer switch happens. This
 155 timer may be used to ensure that event data is consumed and committed
 156 to trace files periodically in case of a low event throughput.
 157
 158 It's also convenient when big sub-buffers are used to cope with sporadic
 159 high event throughput, even if the throughput is normally lower.
 160
 161 Use the option:--switch-timer option to control the switch timer's
 162 period of the channel to create.
 163
 164
 165 Read timer
 166 ~~~~~~~~~~
 167 By default, an internal notification mechanism is used to signal a full
 168 sub-buffer so that it can be consumed. When such notifications must be
 169 avoided, for example in real-time applications, the channel's read timer
 170 can be used instead. When the read timer fires, sub-buffers are checked
 171 for consumption when they are full.
 172
 173 Use the option:--read-timer option to control the read timer's period of
 174 the channel to create.
 175
 176
 177 Monitor timer
 178 ~~~~~~~~~~~~~
 179 When a channel's monitor timer fires, its registered trigger conditions
 180 are evaluated using the current values of its properties (for example,
 181 the current usage of its sub-buffers). When a trigger condition is true,
 182 LTTng executes its associated action. The only type of action currently
 183 supported is to notify one or more user applications.
 184
 185 See the installed $$C/C++$$ headers in `lttng/action`,
 186 `lttng/condition`, `lttng/notification`, and `lttng/trigger` to learn
 187 more about application notifications and triggers.
 188
 189 Use the option:--monitor-timer option to control the monitor timer's
 190 period of the channel to create.
 191
 192
 193 Buffering scheme
 194 ~~~~~~~~~~~~~~~~
 195 In the user space tracing domain, two buffering schemes are available
 196 when creating a channel:
 197
 198 Per-process buffering (option:--buffers-pid option)::
 199     Keep one ring buffer per process.
 200
 201 Per-user buffering (option:--buffers-uid option)::
 202     Keep one ring buffer for all the processes of a single user.
 203
 204 The per-process buffering scheme consumes more memory than the per-user
 205 option if more than one process is instrumented for LTTng-UST.
 206 However, per-process buffering ensures that one process having a high
 207 event throughput won't fill all the shared sub-buffers, only its own.
 208
 209 The Linux kernel tracing domain only has one available buffering scheme
 210 which is to use a single ring buffer for the whole system
 211 (option:--buffers-global option).
 212
 213
 214 Trace files limit and size
 215 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 216 By default, trace files can grow as large as needed. The maximum size
 217 of each trace file written by a channel can be set on creation using the
 218 option:--tracefile-size option. When such a trace file's size reaches
 219 the channel's fixed maximum size, another trace file is created to hold
 220 the next recorded events. A file count is appended to each trace file
 221 name in this case.
 222
 223 If the option:--tracefile-size option is used, the maximum number of
 224 created trace files is unlimited. To limit them, the
 225 option:--tracefile-count option can be used. This option is always used
 226 in conjunction with the option:--tracefile-size option.
 227
 228 For example, consider this command:
 229
 230 [role="term"]
 231 ----
 232 $ lttng enable-channel --kernel --tracefile-size=4096 \
 233                      --tracefile-count=32 my-channel
 234 ----
 235
 236 Here, for each stream, the maximum size of each trace file is
 237 4 kiB and there can be a maximum of 32 different files. When there is
 238 no space left in the last file, _trace file rotation_ happens: the first
 239 file is cleared and new sub-buffers containing events are written there.
 240
 241
 242 include::common-cmd-options-head.txt[]
 243
 244
 245 Domain
 246 ~~~~~~
 247 One of:
 248
 249 option:-k, option:--kernel::
 250     Enable channel in the Linux kernel domain.
 251
 252 option:-u, option:--userspace::
 253     Enable channel in the user space domain.
 254
 255
 256 Target
 257 ~~~~~~
 258 option:-s 'SESSION', option:--session='SESSION'::
 259     Create or enable channel in the tracing session named 'SESSION'
 260     instead of the current tracing session.
 261
 262
 263 Event loss mode
 264 ~~~~~~~~~~~~~~~
 265 One of:
 266
 267 option:--discard::
 268     Discard events when sub-buffers are full (default).
 269
 270 option:--overwrite::
 271     Flight recorder mode: always keep a fixed amount of the latest
 272     data.
 273
 274
 275 Sub-buffers
 276 ~~~~~~~~~~~
 277 option:--num-subbuf='COUNT'::
 278     Use 'COUNT' sub-buffers. Rounded up to the next power of two.
 279 +
 280 Default values:
 281 +
 282 * option:--userspace and option:--buffers-uid options:
 283   {default_ust_uid_channel_subbuf_num}
 284 * option:--userspace and option:--buffers-pid options:
 285   {default_ust_pid_channel_subbuf_num}
 286 * option:--kernel option: {default_kernel_channel_subbuf_num}
 287 * `metadata` channel: {default_metadata_subbuf_num}
 288
 289 option:--subbuf-size='SIZE'::
 290     Set the individual size of sub-buffers to 'SIZE' bytes.
 291     The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
 292     Rounded up to the next power of two.
 293 +
 294 The minimum sub-buffer size, for each tracer, is the maximum value
 295 between the default below and the system's page size. The following
 296 command shows the current system's page size: `getconf PAGE_SIZE`.
 297 +
 298 Default values:
 299 +
 300 * option:--userspace and option:--buffers-uid options:
 301   {default_ust_uid_channel_subbuf_size}
 302 * option:--userspace and option:--buffers-pid options:
 303   {default_ust_pid_channel_subbuf_size}
 304 * option:--kernel option: {default_kernel_channel_subbuf_size}
 305 * `metadata` channel: {default_metadata_subbuf_size}
 306
 307 option:--output='TYPE'::
 308     Set channel's output type to 'TYPE'.
 309 +
 310 Available types: `mmap` (always available) and `splice` (only available
 311 with the option:--kernel option).
 312 +
 313 Default values:
 314 +
 315 * option:--userspace and option:--buffers-uid options: `mmap`
 316 * option:--userspace and option:--buffers-pid options: `mmap`
 317 * option:--kernel option: `splice`
 318 * `metadata` channel: `mmap`
 319
 320 Buffering scheme
 321 ~~~~~~~~~~~~~~~~
 322 One of:
 323
 324 option:--buffers-global::
 325     Use shared sub-buffers for the whole system (only available with the
 326     option:--kernel option).
 327
 328 option:--buffers-pid::
 329     Use different sub-buffers for each traced process (only available
 330     with the the option:--userspace option). This is the default
 331     buffering scheme for user space channels.
 332
 333 option:--buffers-uid::
 334     Use shared sub-buffers for all the processes of the user running
 335     the command (only available with the option:--userspace option).
 336
 337
 338 Trace files
 339 ~~~~~~~~~~~
 340 option:--tracefile-count='COUNT'::
 341     Limit the number of trace files created by this channel to
 342     'COUNT'. 0 means unlimited. Default:
 343     {default_channel_tracefile_count}.
 344 +
 345 Use this option in conjunction with the option:--tracefile-size option.
 346 +
 347 The file count within a stream is appended to each created trace
 348 file. If 'COUNT' files are created and more events need to be recorded,
 349 the first trace file of the stream is cleared and used again.
 350
 351 option:--tracefile-size='SIZE'::
 352     Set the maximum size of each trace file written by
 353     this channel within a stream to 'SIZE' bytes. 0 means unlimited.
 354     Default: {default_channel_tracefile_size}.
 355 +
 356 Note: traces generated with this option may inaccurately report
 357 discarded events as of CTF 1.8.
 358
 359
 360 Timers
 361 ~~~~~~
 362 option:--monitor-timer::
 363     Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
 364     disabled monitor timer.
 365 +
 366 Default values:
 367 +
 368 * option:--userspace and option:--buffers-uid options:
 369   {default_ust_uid_channel_monitor_timer}
 370 * option:--userspace and option:--buffers-pid options:
 371   {default_ust_pid_channel_monitor_timer}
 372 * option:--kernel option: {default_kernel_channel_monitor_timer}
 373
 374 option:--read-timer::
 375     Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
 376     disabled read timer.
 377 +
 378 Default values:
 379 +
 380 * option:--userspace and option:--buffers-uid options:
 381   {default_ust_uid_channel_read_timer}
 382 * option:--userspace and option:--buffers-pid options:
 383   {default_ust_pid_channel_read_timer}
 384 * option:--kernel option: {default_kernel_channel_read_timer}
 385 * `metadata` channel: {default_metadata_read_timer}
 386
 387 option:--switch-timer='PERIODUS'::
 388     Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
 389     a disabled switch timer.
 390 +
 391 Default values:
 392 +
 393 * option:--userspace and option:--buffers-uid options:
 394   {default_ust_uid_channel_switch_timer}
 395 * option:--userspace and option:--buffers-pid options:
 396   {default_ust_pid_channel_switch_timer}
 397 * option:--kernel option: {default_kernel_channel_switch_timer}
 398 * `metadata` channel: {default_metadata_switch_timer}
 399
 400 Timeouts
 401 ~~~~~~~~
 402 option:--blocking-timeout='TIMEOUTUS'::
 403     Set the channel's blocking timeout value to 'TIMEOUTUS' µs
 404     for applications executed with a set `LTTNG_UST_ALLOW_BLOCKING`
 405     environment variable:
 406 +
 407 --
 408 0 (default)::
 409     Do not block.
 410
 411 -1::
 412     Block forever until room is available in the sub-buffer to write the
 413     event record.
 414
 415 __n__, a positive value::
 416     Wait for at most __n__ µs when trying to write into a sub-buffer.
 417 --
 418
 419
 420 include::common-cmd-help-options.txt[]
 421
 422
 423 [[limitations]]
 424 LIMITATIONS
 425 -----------
 426 As of this version of LTTng, it is not possible to perform the following
 427 actions with the `lttng enable-channel` command:
 428
 429 * Reconfigure a channel once it is created.
 430 * Re-enable a disabled channel once its tracing session has been active
 431   at least once.
 432 * Create a channel once its tracing session has been active
 433   at least once.
 434 * Create a user space channel with a given buffering scheme
 435   (option:--buffers-uid or option:--buffers-pid options) and create
 436   a second user space channel with a different buffering scheme in the
 437   same tracing session.
 438
 439
 440 include::common-cmd-footer.txt[]
 441
 442
 443 SEE ALSO
 444 --------
 445 man:lttng-disable-channel(1),
 446 man:lttng(1),
 447 man:lttng-ust(3)