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