2 id: enabling-disabling-channels
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, etc.). A given channel may
11 only be responsible for enabled events belonging to one domain: either
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.
20 The current channels of a given tracing session can be viewed with
23 lttng list some-session
26 where `some-session` is the name of the desired tracing session.
28 To create and enable a channel, use the `enable-channel` command:
31 lttng enable-channel --kernel my-channel
34 This creates a kernel domain channel named `my-channel` with
35 default parameters in the current tracing session.
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, i.e. before the first time you do
42 <code>lttng start</code>.
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.
52 For this reason, make sure to configure your channels properly
53 before starting the tracers for the first time!
57 Here's another example:
60 lttng enable-channel --userspace --session other-session --overwrite \
61 --tracefile-size 1048576 1mib-channel
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
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:
75 lttng enable-event --kernel --channel some-channel sched_switch
78 If no kernel domain channel named `some-channel` existed before calling
79 the above command, it would be created with default parameters.
81 You may enable the same event in two different channels:
84 lttng enable-event --userspace --channel my-channel app:tp
85 lttng enable-event --userspace --channel other-channel app:tp
88 If both channels are enabled, the occurring `app:tp` event
89 generates two recorded events, one for each channel.
91 Disabling a channel is done with the `disable-event` command:
94 lttng disable-event --kernel some-channel
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.