From b4867b3be09b040aa8da32d0fa417ff1ec2a40f9 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 13 Nov 2015 13:42:55 -0500 Subject: [PATCH] doc/man: create lttng-enable-channel(1) and update/fix content MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- doc/man/Makefile.am | 3 +- doc/man/lttng-enable-channel.1.txt | 361 +++++++++++++++++++++++++++++ 2 files changed, 363 insertions(+), 1 deletion(-) create mode 100644 doc/man/lttng-enable-channel.1.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index ed6791ea2..059004938 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -17,7 +17,8 @@ MAN1_NAMES = \ lttng-start \ lttng-stop \ lttng-version \ - lttng-view + lttng-view \ + lttng-enable-channel MAN3_NAMES = MAN8_NAMES = MAN1_NO_ASCIIDOC_NAMES = lttng-crash diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt new file mode 100644 index 000000000..e238830d3 --- /dev/null +++ b/doc/man/lttng-enable-channel.1.txt @@ -0,0 +1,361 @@ +lttng-enable-channel(1) +======================= + + +NAME +---- +lttng-enable-channel - Create or enable LTTng channels + + +SYNOPSIS +-------- +Create a Linux kernel channel: + +[verse] +*lttng* ['GENERAL OPTIONS'] *enable-channel* option:--kernel + [option:--discard | option:--overwrite] [option:--output=(`mmap` | `splice`)] + [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] + [option:--switch-timer='PERIODUS'] [option:--read-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] + [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] + [option:--switch-timer='PERIODUS'] [option:--read-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) + [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']... + + +DESCRIPTION +----------- +The `lttng enable-channel` command can create a new channel, or enable +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 +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. + +When 'CHANNEL' does not name an existing channel, a channel named +'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL' +is enabled. + +Note that the linklttng: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 +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). + +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. + + +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 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. + +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: + +Discard:: + Drop the newest events until a sub-buffer is released. + +Overwrite:: + Clear the sub-buffer containing the oldest recorded events and start + recording the newest events there. This mode is sometimes called + _flight recorder mode_ because it behaves like a flight recorder: + always keep a fixed amount of the latest data. + +Which mechanism to choose depends on the context: prioritize the newest +or the oldest events in the ring buffer? + +Beware that, in overwrite mode (option:--overwrite option), a whole +sub-buffer is abandoned as soon as a new event doesn't find an empty +sub-buffer, whereas in discard mode (option:--discard option), only the +event that doesn't fit is discarded. + +Also note that a count of lost events is incremented and saved in the +trace itself when an event is lost in discard mode, whereas no +information is kept when a sub-buffer gets overwritten before being +committed. + +The probability of losing events, if it is experience in a given +context, can be reduced by fine-tuning the sub-buffers count and size +(see next subsection). + + +Sub-buffers count and size +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The option:--num-subbuf and option:--subbuf-size options respectively +set the number of sub-buffers and their individual size when creating +a new channel. + +Note that there is a noticeable tracer's CPU overhead introduced when +switching sub-buffers (marking a full one as consumable and switching +to an empty one for the following events to be recorded). Knowing this, +the following list presents a few practical situations along with how +to configure sub-buffers for them when creating a channel in overwrite +mode (option:--overwrite option): + +High event throughput:: + In general, prefer bigger sub-buffers to lower the risk of losing + events. Having bigger sub-buffers also ensures a lower sub-buffer + switching frequency. The number of sub-buffers is only meaningful + if the channel is enabled in overwrite mode: in this case, if a + sub-buffer overwrite happens, the other sub-buffers + are left unaltered. + +Low event throughput:: + In general, prefer smaller sub-buffers since the risk of losing + events is already low. Since events happen less frequently, the + sub-buffer switching frequency should remain low and thus the + tracer's overhead should not be a problem. + +Low memory system:: + If the target system has a low memory limit, prefer fewer first, + then smaller sub-buffers. Even if the system is limited in memory, + it is recommended to keep the sub-buffers as big as possible to + avoid a high sub-buffer switching frequency. + +In discard mode (option:--discard option), the sub-buffers count +parameter is pointless: using two sub-buffers and setting their size +according to the requirements of the context is fine. + + +Switch and read timers +~~~~~~~~~~~~~~~~~~~~~~ +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. + + +Buffering scheme +~~~~~~~~~~~~~~~~ +In the user space tracing domain, two buffering schemes are available +when creating a channel: + +Per-process buffering (option:--buffers-pid option):: + Keep one ring buffer per process. + +Per-user buffering (option:--buffers-uid option):: + Keep one ring buffer for all the processes of a single user. + +The per-process buffering scheme consumes more memory than the per-user +option if more than one process is instrumented for LTTng-UST. +However, per-process buffering ensures that one process having a high +event throughput won't fill all the shared sub-buffers, only its own. + +The Linux kernel tracing domain only has one available buffering scheme +which is to use a single ring buffer for the whole system +(option:--buffers-global option). + + +Trace files limit and size +~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, trace files can grow as large as needed. The maximum size +of each trace file written by a channel can be set on creation using the +option:--tracefile-size option. When such a trace file's size reaches +the channel's fixed maximum size, another trace file is created to hold +the next recorded events. A file count is appended to each trace file +name in this case. + +If the option:--tracefile-size option is used, the maximum number of +created trace files is unlimited. To limit them, the +option:--tracefile-count option can be used. This option is always used +in conjunction with the option:--tracefile-size option. + +For example, consider this command: + +----------------------------------------------------- +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. + + +include::common-cmd-options-head.txt[] + + +Domain +~~~~~~ +One of: + +option:-k, option:--kernel:: + Enable channel in the Linux kernel domain. + +option:-u, option:--userspace:: + Enable channel in the user space domain. + + +Target +~~~~~~ +option:-s, option:--session='SESSION':: + Create or enable channel in the tracing session named 'SESSION' + instead of the current tracing session. + + +Event loss mode +~~~~~~~~~~~~~~~ +One of: + +option:--discard:: + Discard events when sub-buffers are full (default). + +option:--overwrite:: + Flight recorder mode: always keep a fixed amount of the latest + data. + + +Sub-buffers +~~~~~~~~~~~ +option:--num-subbuf='COUNT':: + Use 'COUNT' sub-buffers. Rounded up to the next power of two. ++ +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:--output='TYPE':: + Set channel's output type to 'TYPE'. ++ +Available types: `mmap` (always available) and `splice` (only available +with the option:--kernel option). ++ +Default values: ++ +* option:--userspace and option:--buffers-uid options: `mmap` +* option:--userspace and option:--buffers-pid options: `mmap` +* option:--kernel option: `splice` +* `metadata` channel: `mmap` + +Buffering scheme +~~~~~~~~~~~~~~~~ +One of: + +option:--buffers-global:: + Use shared sub-buffers for the whole system (only available with the + option:--kernel option). + +option:--buffers-pid:: + Use different sub-buffers for each traced process (only available + with the the option:--userspace option). This is the default + buffering scheme for user space channels. + +option:--buffers-uid:: + Use shared sub-buffers for all the processes of the user running + the command (only available with the option:--userspace option). + + +Trace files +~~~~~~~~~~~ +option:--tracefile-count='COUNT':: + Limit the number of trace files created by this channel to + 'COUNT'. 0 means unlimited. Default: 0. ++ +Use this option in conjunction with the option:--tracefile-size option. ++ +The file count within a stream is appended to each created trace +file. If 'COUNT' files are created and more events need to be recorded, +the first trace file of the stream is cleared and used again. + +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. ++ +Note: traces generated with this option may inaccurately report +discarded events as of CTF 1.8. + + +Timers +~~~~~~ +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:--switch-timer='PERIODUS':: + Set the channel's switch timer's period to 'PERIODUS' µs. 0 means + a disabled switch timer. Default: 0. + + +include::common-cmd-help-options.txt[] + + +include::common-cmd-footer.txt[] + + +SEE ALSO +-------- +linklttng:lttng-disable-channel(1), +linklttng:lttng(1) -- 2.34.1