contents/using-lttng/controlling-tracing/enabling-disabling-channels/fine-tuning-channels.md

   1 ---
   2 id: fine-tuning-channels
   3 ---
   4
   5 There are various parameters that may be fine-tuned with the
   6 `enable-channel` command. The latter are well documented in
   7 <a href="/man/1/lttng" class="ext">the man page of `lttng`</a>
   8 and in the [Channel](#doc-channel) section of the
   9 [Understanding LTTng](#doc-understanding-lttng) chapter. For basic
  10 tracing needs, their default values should be just fine, but here are a
  11 few examples to break the ice.
  12
  13 As the frequency of recorded events increases&mdash;either because the
  14 event throughput is actually higher or because you enabled more events
  15 than usual&mdash;_event loss_ might be experienced. Since LTTng never
  16 waits, by design, for sub-buffer space availability (non-blocking
  17 tracer), when a sub-buffer is full and no empty sub-buffers are left,
  18 there are two possible outcomes: either the new events that do not fit
  19 are rejected, or they start replacing the oldest recorded events.
  20 The choice of which algorithm to use is a per-channel parameter, the
  21 default being discarding the newest events until there is some space
  22 left. If your situation always needs the latest events at the expense
  23 of writing over the oldest ones, create a channel with the `--overwrite`
  24 option:
  25
  26 <pre class="term">
  27 lttng enable-channel --kernel --overwrite my-channel
  28 </pre>
  29
  30 When an event is lost, it means no space was available in any
  31 sub-buffer to accommodate it. Thus, if you want to cope with sporadic
  32 high event throughput situations and avoid losing events, you need to
  33 allocate more room for storing them in memory. This can be done by
  34 either increasing the size of sub-buffers or by adding sub-buffers.
  35 The following example creates a user space domain channel with
  36 16&nbsp;sub-buffers of 512&nbsp;kiB each:
  37
  38 <pre class="term">
  39 lttng enable-channel --userspace --num-subbuf 16 --subbuf-size 512k big-channel
  40 </pre>
  41
  42 Both values need to be powers of two, otherwise they are rounded up
  43 to the next one.
  44
  45 Two other interesting available parameters of `enable-channel` are
  46 `--tracefile-size` and `--tracefile-count`, which respectively limit
  47 the size of each trace file and the their count for a given channel.
  48 When the number of written trace files reaches its limit for a given
  49 channel-CPU pair, the next trace file overwrites the very first
  50 one. The following example creates a kernel domain channel with a
  51 maximum of three trace files of 1&nbsp;MiB each:
  52
  53 <pre class="term">
  54 lttng enable-channel --kernel --tracefile-size 1M --tracefile-count 3 my-channel
  55 </pre>
  56
  57 An efficient way to make sure lots of events are generated is enabling
  58 all kernel events in this channel and starting the tracer:
  59
  60 <pre class="term">
  61 lttng enable-event --kernel --all --channel my-channel
  62 lttng start
  63 </pre>
  64
  65 After a few seconds, look at trace files in your tracing session
  66 output directory. For two CPUs, it should look like:
  67
  68 ~~~ text
  69 my-channel_0_0    my-channel_1_0
  70 my-channel_0_1    my-channel_1_1
  71 my-channel_0_2    my-channel_1_2
  72 ~~~
  73
  74 Amongst the files above, you might see one in each group with a size
  75 lower than 1&nbsp;MiB: they are the files currently being written.
  76
  77 Since all those small files are valid LTTng trace files, LTTng trace
  78 viewers may read them. It is the viewer's responsibility to properly
  79 merge the streams so as to present an ordered list to the user.
  80 <a href="http://www.efficios.com/babeltrace" class="ext">Babeltrace</a>
  81 merges LTTng trace files correctly and is fast at doing it.