Create a Linux kernel channel:
[verse]
-*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--kernel
- [option:--discard | option:--overwrite] [option:--output=(`mmap` | `splice`)]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
+ [option:--overwrite] [option:--output=(`mmap` | `splice`)]
[option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
[option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
+ [option:--monitor-timer='PERIODUS']
[option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
[option:--session='SESSION'] 'CHANNEL'
Create a user space channel:
[verse]
-*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--userspace
- [option:--discard | option:--overwrite] [option:--buffers-pid]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
+ [option:--overwrite] [option:--buffers-pid]
[option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
[option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
+ [option:--monitor-timer='PERIODUS'] [option:--blocking-timeout='TIMEOUTUS']
[option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
[option:--session='SESSION'] 'CHANNEL'
Enable existing channel(s):
[verse]
-*lttng* ['GENERAL OPTIONS'] *enable-channel* (option:--userspace | option:--kernel)
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
[option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
one or more existing and disabled ones.
A channel is the owner of sub-buffers holding recorded events. Event,
-rules, when created using linklttng:lttng-enable-event(1), are always
+rules, when created using man:lttng-enable-event(1), are always
assigned to a channel. When creating a new channel, many parameters
related to those sub-buffers can be fine-tuned. They are described in
the subsections below.
'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
is enabled.
-Note that the linklttng:lttng-enable-event(1) command can automatically
+Note that the man:lttng-enable-event(1) command can automatically
create default channels when no channel exist.
A channel is always contained in a tracing session
-(see linklttng:lttng-create(1) for creating a tracing session). The
+(see man:lttng-create(1) for creating a tracing session). The
session in which a channel is created using `lttng enable-channel` can
be specified using the option:--session option. If the option:--session
option is omitted, the current tracing session is targeted.
Existing enabled channels can be disabled using
-linklttng:lttng-disable-channel(1). Channels of a given session can be
-listed using linklttng:lttng-list(1).
+man:lttng-disable-channel(1). Channels of a given session can be
+listed using man:lttng-list(1).
-As of this version of LTTng, it is not possible to:
-
-* Reconfigure a channel once it is created.
-* Re-enable a disabled channel once its tracing session has been active
- at least once.
-* Create a channel once its tracing session has been active
- at least once.
-* Create a user space channel with a given buffering scheme
- (option:--buffers-uid or option:--buffers-pid options) and create
- a second user space channel with a different buffering scheme in the
- same tracing session.
+See the <<limitations,LIMITATIONS>> section below for a list of
+limitations of this command to consider.
Event loss modes
according to the requirements of the context is fine.
-Switch and read timers
-~~~~~~~~~~~~~~~~~~~~~~
+Switch timer
+~~~~~~~~~~~~
When a channel's switch timer fires, a sub-buffer switch happens. This
timer may be used to ensure that event data is consumed and committed
to trace files periodically in case of a low event throughput.
It's also convenient when big sub-buffers are used to cope with sporadic
high event throughput, even if the throughput is normally lower.
-By default, a notification mechanism is used to signal a full sub-buffer
-so that it can be consumed. When such notifications must be avoided,
-for example in real-time applications, the channel's read timer can be
-used instead. When the read timer fires, sub-buffers are checked for
-consumption when they are full.
+Use the option:--switch-timer option to control the switch timer's
+period of the channel to create.
+
+
+Read timer
+~~~~~~~~~~
+By default, an internal notification mechanism is used to signal a full
+sub-buffer so that it can be consumed. When such notifications must be
+avoided, for example in real-time applications, the channel's read timer
+can be used instead. When the read timer fires, sub-buffers are checked
+for consumption when they are full.
+
+Use the option:--read-timer option to control the read timer's period of
+the channel to create.
+
+
+Monitor timer
+~~~~~~~~~~~~~
+When a channel's monitor timer fires, its registered trigger conditions
+are evaluated using the current values of its properties (for example,
+the current usage of its sub-buffers). When a trigger condition is true,
+LTTng executes its associated action. The only type of action currently
+supported is to notify one or more user applications.
+
+See the installed $$C/C++$$ headers in `lttng/action`,
+`lttng/condition`, `lttng/notification`, and `lttng/trigger` to learn
+more about application notifications and triggers.
+
+Use the option:--monitor-timer option to control the monitor timer's
+period of the channel to create.
Buffering scheme
For example, consider this command:
[role="term"]
------------------------------------------------------
-lttng enable-channel --kernel --tracefile-size=4096 \
+----
+$ lttng enable-channel --kernel --tracefile-size=4096 \
--tracefile-count=32 my-channel
------------------------------------------------------
+----
Here, for each stream, the maximum size of each trace file is
4 kiB and there can be a maximum of 32 different files. When there is
Target
~~~~~~
-option:-s, option:--session='SESSION'::
+option:-s 'SESSION', option:--session='SESSION'::
Create or enable channel in the tracing session named 'SESSION'
instead of the current tracing session.
+
Default values:
+
-* `metadata` channel: 2
-* Everything else: 4
-
-option:--subbuf-size='SIZE'::
- Set the individual size of sub-buffers to 'SIZE' bytes.
- The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
- Rounded up to the next power of two.
-+
-The minimum sub-buffer size, for each tracer, is the maximum value
-between the default below and the system's page size. The following
-command shows the current system's page size: `getconf PAGE_SIZE`.
-+
-Default values:
-+
-* option:--userspace and option:--buffers-uid options: `128k`
-* option:--userspace and option:--buffers-pid options: `4k`
-* option:--kernel option: `256k`
-* `metadata` channel: `4k`
+* option:--userspace and option:--buffers-uid options:
+ {default_ust_uid_channel_subbuf_num}
+* option:--userspace and option:--buffers-pid options:
+ {default_ust_pid_channel_subbuf_num}
+* option:--kernel option: {default_kernel_channel_subbuf_num}
+* `metadata` channel: {default_metadata_subbuf_num}
option:--output='TYPE'::
Set channel's output type to 'TYPE'.
* option:--kernel option: `splice`
* `metadata` channel: `mmap`
+option:--subbuf-size='SIZE'::
+ Set the individual size of sub-buffers to 'SIZE' bytes.
+ The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
+ Rounded up to the next power of two.
++
+The minimum sub-buffer size, for each tracer, is the maximum value
+between the default below and the system's page size. The following
+command shows the current system's page size: `getconf PAGE_SIZE`.
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options:
+ {default_ust_uid_channel_subbuf_size}
+* option:--userspace and option:--buffers-pid options:
+ {default_ust_pid_channel_subbuf_size}
+* option:--kernel option: {default_kernel_channel_subbuf_size}
+* `metadata` channel: {default_metadata_subbuf_size}
+
+
Buffering scheme
~~~~~~~~~~~~~~~~
One of:
~~~~~~~~~~~
option:--tracefile-count='COUNT'::
Limit the number of trace files created by this channel to
- 'COUNT'. 0 means unlimited. Default: 0.
+ 'COUNT'. 0 means unlimited. Default:
+ {default_channel_tracefile_count}.
+
Use this option in conjunction with the option:--tracefile-size option.
+
option:--tracefile-size='SIZE'::
Set the maximum size of each trace file written by
this channel within a stream to 'SIZE' bytes. 0 means unlimited.
- Default: 0.
+ Default: {default_channel_tracefile_size}.
+
Note: traces generated with this option may inaccurately report
discarded events as of CTF 1.8.
Timers
~~~~~~
+option:--monitor-timer::
+ Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
+ disabled monitor timer.
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options:
+ {default_ust_uid_channel_monitor_timer}
+* option:--userspace and option:--buffers-pid options:
+ {default_ust_pid_channel_monitor_timer}
+* option:--kernel option: {default_kernel_channel_monitor_timer}
+
option:--read-timer::
Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
disabled read timer.
+
Default values:
+
-* option:--userspace and option:--buffers-uid options: 0
-* option:--userspace and option:--buffers-pid options: 0
-* option:--kernel option: 200000
-* `metadata` channel: 0
+* option:--userspace and option:--buffers-uid options:
+ {default_ust_uid_channel_read_timer}
+* option:--userspace and option:--buffers-pid options:
+ {default_ust_pid_channel_read_timer}
+* option:--kernel option: {default_kernel_channel_read_timer}
+* `metadata` channel: {default_metadata_read_timer}
option:--switch-timer='PERIODUS'::
Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
- a disabled switch timer. Default: 0.
+ a disabled switch timer.
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options:
+ {default_ust_uid_channel_switch_timer}
+* option:--userspace and option:--buffers-pid options:
+ {default_ust_pid_channel_switch_timer}
+* option:--kernel option: {default_kernel_channel_switch_timer}
+* `metadata` channel: {default_metadata_switch_timer}
+
+Timeouts
+~~~~~~~~
+option:--blocking-timeout='TIMEOUTUS'::
+ Set the channel's blocking timeout value to 'TIMEOUTUS' µs
+ for applications executed with a set `LTTNG_UST_ALLOW_BLOCKING`
+ environment variable:
++
+--
+0 (default)::
+ Do not block.
+
+-1::
+ Block forever until room is available in the sub-buffer to write the
+ event record.
+
+__n__, a positive value::
+ Wait for at most __n__ µs when trying to write into a sub-buffer.
+--
include::common-cmd-help-options.txt[]
+[[limitations]]
+LIMITATIONS
+-----------
+As of this version of LTTng, it is not possible to perform the following
+actions with the `lttng enable-channel` command:
+
+* Reconfigure a channel once it is created.
+* Re-enable a disabled channel once its tracing session has been active
+ at least once.
+* Create a channel once its tracing session has been active
+ at least once.
+* Create a user space channel with a given buffering scheme
+ (option:--buffers-uid or option:--buffers-pid options) and create
+ a second user space channel with a different buffering scheme in the
+ same tracing session.
+
+
include::common-cmd-footer.txt[]
SEE ALSO
--------
-linklttng:lttng-disable-channel(1),
-linklttng:lttng(1)
+man:lttng-disable-channel(1),
+man:lttng(1),
+man:lttng-ust(3)
projects / lttng-tools.git / blobdiff