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

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