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:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid]
[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'
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
~~~~~~~~~~~~~~~~
-LTTng tracers are non-blocking: when no empty sub-buffer exists,
-losing events is acceptable when the alternative would be to cause
-substantial delays in the instrumented application's execution.
+LTTng tracers are non-blocking by default: when no empty sub-buffer
+exists, losing events is acceptable when the alternative would be to
+cause substantial delays in the instrumented application's execution.
LTTng privileges performance over integrity, aiming at perturbing the
traced system as little as possible in order to make tracing of subtle
race conditions and rare interrupt cascades possible.
+You can allow the user space tracer to block with a
+option:--blocking-timeout option set to a positive value or to `inf`,
+and with an application which is instrumented with LTTng-UST started
+with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable. See
+man:lttng-ust(3) for more details.
+
When it comes to losing events because no empty sub-buffer is available,
the channel's event loss mode, specified by one of the option:--discard
and option:--overwrite options, determines what to do amongst:
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
no space left in the last file, _trace file rotation_ happens: the first
file is cleared and new sub-buffers containing events are written there.
+LTTng does not guarantee that you can view the trace of an active
+tracing session (before you run the man:lttng-stop(1) command), even
+with multiple trace files, because LTTng could overwrite them at any
+moment, or some of them could be incomplete. You can archive a
+tracing session's current trace chunk while the tracing session is
+active to obtain an unmanaged and self-contained LTTng trace: see
+man:lttng-rotate(1) and man:lttng-enable-rotation(1).
+
include::common-cmd-options-head.txt[]
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.
Event loss mode
~~~~~~~~~~~~~~~
+option:--blocking-timeout='TIMEOUTUS'::
+ Set the channel's blocking timeout value to 'TIMEOUTUS' µs for
+ instrumented applications executed with a set
+ `LTTNG_UST_ALLOW_BLOCKING` environment variable:
++
+--
+0 (default)::
+ Do not block (non-blocking mode).
+
+`inf`::
+ 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.
+ After __n__ µs, discard the event record.
+--
++
+This option is only available with the option:--userspace option and
+without the option:--overwrite option.
+
One of:
option:--discard::
+
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}
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