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

   1 ---
   2 id: enabling-disabling-channels
   3 ---
   4
   5 [As mentioned](#doc-event) in the
   6 [Understanding LTTng](#doc-understanding-lttng) chapter, enabled
   7 events are contained in a specific channel, itself contained in a
   8 specific tracing session. A channel is a group of events with
   9 tunable parameters (event loss mode, sub-buffer size, number of
  10 sub-buffers, trace file sizes and count, to name a few). A given channel
  11 may only be responsible for enabled events belonging to one domain:
  12 either kernel or user space.
  13
  14 If you only used the `create`, `enable-event` and `start`/`stop`
  15 commands of the `lttng` tool so far, one or two channels were
  16 automatically created for you (one for the kernel domain and/or one
  17 for the user space domain). The default channels are both named
  18 `channel0`; channels from different domains may have the same name.
  19
  20 The current channels of a given tracing session can be viewed with
  21
  22 <pre class="term">
  23 lttng list some-session
  24 </pre>
  25
  26 where `some-session` is the name of the desired tracing session.
  27
  28 To create and enable a channel, use the `enable-channel` command:
  29
  30 <pre class="term">
  31 lttng enable-channel --kernel my-channel
  32 </pre>
  33
  34 This creates a kernel domain channel named `my-channel` with
  35 default parameters in the current tracing session.
  36
  37 <div class="tip">
  38 <p>
  39     <span class="t">Note:</span>Because of a current limitation, all
  40     channels must be <em>created</em> prior to beginning tracing in a
  41     given tracing session, that is before the first time you do
  42     <code>lttng start</code>.
  43 </p>
  44 <p>
  45     Since a channel is automatically created by
  46     <code>enable-event</code> only for the specified domain, you cannot,
  47     for example, enable a kernel domain event, start tracing and then
  48     enable a user space domain event because no user space channel
  49     exists yet and it's too late to create one.
  50 </p>
  51 <p>
  52     For this reason, make sure to configure your channels properly
  53     before starting the tracers for the first time!
  54 </p>
  55 </div>
  56
  57 Here's another example:
  58
  59 <pre class="term">
  60 lttng enable-channel --userspace --session other-session --overwrite \
  61                      --tracefile-size 1048576 1mib-channel
  62 </pre>
  63
  64 This creates a user space domain channel named `1mib-channel` in
  65 the tracing session named `other-session` that loses new events by
  66 overwriting previously recorded events (instead of the default mode of
  67 discarding newer ones) and saves trace files with a maximum size of
  68 1&nbsp;MiB each.
  69
  70 Note that channels may also be created using the `--channel` option of
  71 the `enable-event` command when the provided channel name doesn't exist
  72 for the specified domain:
  73
  74 <pre class="term">
  75 lttng enable-event --kernel --channel some-channel sched_switch
  76 </pre>
  77
  78 If no kernel domain channel named `some-channel` existed before calling
  79 the above command, it would be created with default parameters.
  80
  81 You may enable the same event in two different channels:
  82
  83 <pre class="term">
  84 lttng enable-event --userspace --channel my-channel app:tp
  85 lttng enable-event --userspace --channel other-channel app:tp
  86 </pre>
  87
  88 If both channels are enabled, the occurring `app:tp` event
  89 generates two recorded events, one for each channel.
  90
  91 Disabling a channel is done with the `disable-event` command:
  92
  93 <pre class="term">
  94 lttng disable-event --kernel some-channel
  95 </pre>
  96
  97 The state of a channel precedes the individual states of events within
  98 it: events belonging to a disabled channel, even if they are
  99 enabled, won't be recorded.
 100