From 1630f5ee51c78fa9354d4864b1ddec1a69af6e0c Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 31 Jul 2017 14:08:28 -0400 Subject: [PATCH] lttng-enable-channel(1): document --monitor-timer 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/asciidoc-attrs.conf.in | 3 ++ doc/man/lttng-enable-channel.1.txt | 54 +++++++++++++++++++++++++----- 2 files changed, 49 insertions(+), 8 deletions(-) diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in index 4d727e74a..bf6333c91 100644 --- a/doc/man/asciidoc-attrs.conf.in +++ b/doc/man/asciidoc-attrs.conf.in @@ -10,6 +10,7 @@ default_kernel_channel_read_timer="@DEFAULT_KERNEL_CHANNEL_READ_TIMER@" default_kernel_channel_subbuf_num="@DEFAULT_KERNEL_CHANNEL_SUBBUF_NUM@" default_kernel_channel_subbuf_size="@DEFAULT_KERNEL_CHANNEL_SUBBUF_SIZE@" default_kernel_channel_switch_timer="@DEFAULT_KERNEL_CHANNEL_SWITCH_TIMER@" +default_kernel_channel_monitor_timer="@DEFAULT_KERNEL_CHANNEL_MONITOR_TIMER@" default_lttng_live_timer="@DEFAULT_LTTNG_LIVE_TIMER@" default_metadata_cache_size="@DEFAULT_METADATA_CACHE_SIZE@" default_metadata_read_timer="@DEFAULT_METADATA_READ_TIMER@" @@ -24,11 +25,13 @@ default_ust_pid_channel_read_timer="@DEFAULT_UST_PID_CHANNEL_READ_TIMER@" default_ust_pid_channel_subbuf_num="@DEFAULT_UST_PID_CHANNEL_SUBBUF_NUM@" default_ust_pid_channel_subbuf_size="@DEFAULT_UST_PID_CHANNEL_SUBBUF_SIZE@" default_ust_pid_channel_switch_timer="@DEFAULT_UST_PID_CHANNEL_SWITCH_TIMER@" +default_ust_pid_channel_monitor_timer="@DEFAULT_UST_PID_CHANNEL_MONITOR_TIMER@" default_ust_uid_channel_live_timer="@DEFAULT_UST_UID_CHANNEL_LIVE_TIMER@" default_ust_uid_channel_read_timer="@DEFAULT_UST_UID_CHANNEL_READ_TIMER@" default_ust_uid_channel_subbuf_num="@DEFAULT_UST_UID_CHANNEL_SUBBUF_NUM@" default_ust_uid_channel_subbuf_size="@DEFAULT_UST_UID_CHANNEL_SUBBUF_SIZE@" default_ust_uid_channel_switch_timer="@DEFAULT_UST_UID_CHANNEL_SWITCH_TIMER@" +default_ust_uid_channel_monitor_timer="@DEFAULT_UST_UID_CHANNEL_MONITOR_TIMER@" default_agent_bind_address="@DEFAULT_AGENT_BIND_ADDRESS@" default_network_control_bind_address="@DEFAULT_NETWORK_CONTROL_BIND_ADDRESS@" default_network_data_bind_address="@DEFAULT_NETWORK_DATA_BIND_ADDRESS@" diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index bec090642..cad26a864 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -16,6 +16,7 @@ Create a Linux kernel channel: [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' @@ -26,7 +27,7 @@ Create a user space channel: [option:--overwrite] [option:--buffers-pid] [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] - [option:--blocking-timeout='TIMEOUTUS'] + [option:--monitor-timer='PERIODUS'] [option:--blocking-timeout='TIMEOUTUS'] [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] [option:--session='SESSION'] 'CHANNEL' @@ -148,8 +149,8 @@ parameter is pointless: using two sub-buffers and setting their size 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. @@ -157,11 +158,36 @@ 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 @@ -333,6 +359,18 @@ 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. -- 2.34.1