Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
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 | |
ba3b1994 PP |
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. | |
5e0cbfb0 PP |
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 | ||
47bfcb75 | 34 | This creates a kernel domain channel named `my-channel` with |
5e0cbfb0 PP |
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 | |
4d46e8c0 | 41 | given tracing session, that is before the first time you do |
5e0cbfb0 PP |
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 | ||
47bfcb75 | 64 | This creates a user space domain channel named `1mib-channel` in |
5e0cbfb0 PP |
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 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 | ||
47bfcb75 PP |
88 | If both channels are enabled, the occurring `app:tp` event |
89 | generates two recorded events, one for each channel. | |
5e0cbfb0 PP |
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 |