| 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—either because the |
| 14 | event throughput is actually higher or because you enabled more events |
| 15 | than usual—_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 sub-buffers of 512 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 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 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. |