1 lttng-enable-channel(1)
2 =======================
8 lttng-enable-channel - Create or enable LTTng channels
13 Create a Linux kernel channel:
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
17 [option:--discard | option:--overwrite] [option:--output=(**mmap** | **splice**)]
18 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
19 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
20 [option:--monitor-timer='PERIODUS'] [option:--buffers-global]
21 [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
22 [option:--session='SESSION'] 'CHANNEL'
24 Create a user space channel:
27 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
28 [option:--overwrite | [option:--discard] option:--blocking-timeout='TIMEOUTUS']
29 [option:--output=**mmap**] [option:--buffers-uid | option:--buffers-pid]
30 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
31 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
32 [option:--monitor-timer='PERIODUS']
33 [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
34 [option:--session='SESSION'] 'CHANNEL'
39 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
40 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
45 The `lttng enable-channel` command does one of:
47 * Create a channel named 'CHANNEL'.
49 * Enable one or more disabled channels named 'CHANNEL'
50 (non-option argument, comma-separated).
52 See man:lttng-concepts(7) to learn more about channels.
54 The channel(s) to create or enable belong to:
56 With the option:--session='SESSION' option::
57 The tracing session named 'SESSION'.
59 Without the option:--session option::
60 The current tracing session (see man:lttng-concepts(7) to learn more
61 about the current tracing session).
63 NOTE: The man:lttng-enable-event(1) command can automatically create a
64 default channel when no channel exists for the provided tracing domain.
66 List the channels of a given tracing session with the
67 man:lttng-list(1) and man:lttng-status(1) commands.
69 Disable an enabled channel with the man:lttng-disable-channel(1)
74 As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
75 operations with the `enable-channel` command:
77 * Change an attribute of an existing channel.
79 * Enable a disabled channel once its tracing session has been active
80 (started; see man:lttng-start(1)) at least once.
82 * Create a channel once its tracing session has been active at least
85 * Create a user space channel with a given buffering scheme
86 (option:--buffers-uid or option:--buffers-pid options) and create a
87 second user space channel with a different buffering scheme in the
92 include::common-cmd-options-head.txt[]
99 option:-k, option:--kernel::
100 Create or enable channels in the Linux kernel domain.
102 option:-u, option:--userspace::
103 Create or enable channels in the user space domain.
108 option:-s 'SESSION', option:--session='SESSION'::
109 Create or enable channels in the tracing session named 'SESSION'
110 instead of the current tracing session.
117 option:--buffers-global::
118 Allocate a single set of ring buffers for the whole system.
120 Only available with the option:--kernel option.
122 As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
123 for the Linux kernel tracing domain, but this may change in the future.
125 option:--buffers-pid::
126 Allocate one set of ring buffers (one per CPU) for each instrumented
130 If you connect to the root session daemon::
133 See the ``Session daemon connection'' section of man:lttng(1) to learn
134 how a user application connects to a session daemon.
140 Only available with the option:--userspace option.
142 option:--buffers-uid::
143 Allocate one set of ring buffers (one per CPU) shared by all the
144 instrumented processes of:
147 If you connect to the root session daemon::
150 See the ``Session daemon connection'' section of man:lttng(1) to learn
151 how a user application connects to a session daemon.
157 Only available with the option:--userspace option.
159 As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme
160 for the user space tracing domain, but this may change in the future.
163 Event record loss mode
164 ~~~~~~~~~~~~~~~~~~~~~~
165 option:--blocking-timeout='TIMEOUTUS'::
166 Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs
167 for instrumented applications executed with a set
168 `LTTNG_UST_ALLOW_BLOCKING` environment variable.
170 'TIMEOUTUS' is one of:
174 Do not block (non-blocking mode).
177 Block forever until a sub-buffer is available to write the event
180 __N__, a positive value::
181 Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer.
182 After __N__{nbsp}µs, discard the event record.
185 This option is only available with both the option:--userspace and
186 option:--discard options.
191 Discard event records when there's no available sub-buffer.
193 As of LTTng{nbsp}{lttng_version}, this is the default event record loss
194 mode, but this may change in the future.
197 Overwrite the whole sub-buffer containing the oldest event records
198 when there's no available sub-buffer (flight recorder mode).
203 option:--num-subbuf='COUNT'::
204 Use 'COUNT' sub-buffers per ring buffer.
206 The effective value is 'COUNT' rounded up to the next power of two.
210 option:--userspace and option:--buffers-uid options:::
211 +{default_ust_uid_channel_subbuf_num}+
212 option:--userspace and option:--buffers-pid options:::
213 +{default_ust_pid_channel_subbuf_num}+
214 option:--kernel and option:--buffers-global options:::
215 +{default_kernel_channel_subbuf_num}+
216 `metadata` channel:::
217 +{default_metadata_subbuf_num}+
219 option:--output='TYPE'::
220 Set channel's output type to 'TYPE'.
226 Share ring buffers between the tracer and the consumer daemon with
227 the man:mmap(2) system call.
230 Share ring buffers between the tracer and the consumer daemon
231 with the man:splice(2) system call.
233 Only available with the option:--kernel option.
238 option:--userspace and option:--buffers-uid options:::
240 option:--userspace and option:--buffers-pid options:::
242 option:--kernel and option:--buffers-global options:::
244 `metadata` channel:::
247 option:--subbuf-size='SIZE'::
248 Set the size of each sub-buffer to 'SIZE' bytes.
250 The effective value is 'SIZE' rounded up to the next power of two.
252 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
255 The minimum sub-buffer size, for each tracer, is the maximum value
256 between the default below and the system page size (see man:getconf(1)
257 with the `PAGE_SIZE` variable).
261 option:--userspace and option:--buffers-uid options:::
262 +{default_ust_uid_channel_subbuf_size}+
263 option:--userspace and option:--buffers-pid options:::
264 +{default_ust_pid_channel_subbuf_size}+
265 option:--kernel and option:--buffers-global options:::
266 +{default_kernel_channel_subbuf_size}+
267 `metadata` channel:::
268 +{default_metadata_subbuf_size}+
273 option:--tracefile-count='COUNT'::
274 Limit the number of trace files which LTTng writes for this channel
277 'COUNT' set to `0` means ``unlimited''.
279 Default: +{default_channel_tracefile_count}+.
281 You must also use the option:--tracefile-size option with this option.
283 option:--tracefile-size='SIZE'::
284 Set the maximum size of each trace file which LTTng writes for
285 this channel to __SIZE__{nbsp}bytes.
287 'SIZE' set to `0` means ``unlimited''.
289 Default: +{default_channel_tracefile_size}+.
291 NOTE: Data streams which LTTng writes for a channel configured with this
292 option may inaccurately report discarded event records as of
298 option:--monitor-timer='PERIODUS'::
299 Set the period of the monitor timer of the channel to
300 __PERIODUS__{nbsp}µs.
302 Set 'PERIODUS' to `0` to disable the monitor timer.
306 option:--userspace and option:--buffers-uid options:::
307 +{default_ust_uid_channel_monitor_timer}+
308 option:--userspace and option:--buffers-pid options:::
309 +{default_ust_pid_channel_monitor_timer}+
310 option:--kernel and option:--buffers-global options:::
311 +{default_kernel_channel_monitor_timer}+
313 option:--read-timer='PERIODUS'::
314 Set the period of the read timer of the channel to
315 __PERIODUS__{nbsp}µs.
317 Set 'PERIODUS' to `0` to disable the read timer.
321 option:--userspace and option:--buffers-uid options:::
322 +{default_ust_uid_channel_read_timer}+
323 option:--userspace and option:--buffers-pid options:::
324 +{default_ust_pid_channel_read_timer}+
325 option:--kernel and option:--buffers-global options:::
326 +{default_kernel_channel_read_timer}+
327 `metadata` channel:::
328 +{default_metadata_read_timer}+
330 option:--switch-timer='PERIODUS'::
331 Set the period of the switch timer of the channel to
332 __PERIODUS__{nbsp}µs.
334 Set 'PERIODUS' to `0` to disable the switch timer.
338 option:--userspace and option:--buffers-uid options:::
339 +{default_ust_uid_channel_switch_timer}+
340 option:--userspace and option:--buffers-pid options:::
341 +{default_ust_pid_channel_switch_timer}+
342 option:--kernel and option:--buffers-global options:::
343 +{default_kernel_channel_switch_timer}+
344 `metadata` channel:::
345 +{default_metadata_switch_timer}+
348 include::common-cmd-help-options.txt[]
351 include::common-cmd-footer.txt[]
357 man:lttng-disable-channel(1),
359 man:lttng-concepts(7)