lttng-enable-channel(1): document --monitor-timer

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in
index 4d727e74a1c3d3dc9bf511d8ea8015e642393fc1..bf6333c9127152f7f4ffadb44c4063d729b8182e 100644 (file)
--- 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_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@"
 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_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_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@"
 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 bec0906428c5bfba6e9f91ab3e8f783cd96b472e..cad26a8643edf052a67bd0aa0738cfe834c14ba5 100644 (file)
--- 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:--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'
 
       [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:--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'
 
       [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.
 
 
 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.
 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.
 
 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
 
 
 Buffering scheme


@@ -333,6 +359,18 @@ discarded events as of CTF 1.8.
 
 Timers
 ~~~~~~
 
 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.
 option:--read-timer::
     Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
     disabled read timer.