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