X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-channel.1.txt;h=c4781c0f1953bfaad67382a9f948a686cd09fe9c;hp=b5e7c947d20eda9c65bfd5dc75c96ab309353146;hb=55d7bb027104ac0afd80be872e0ff7ebb832216e;hpb=d4f093aa457acf5492c099f40badcc8379c95fe9 diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index b5e7c947d..c4781c0f1 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -12,27 +12,29 @@ SYNOPSIS 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']... @@ -42,7 +44,7 @@ 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 +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. @@ -51,30 +53,21 @@ 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 +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 <> section below for a list of +limitations of this command to consider. Event loss modes @@ -156,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. @@ -165,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 @@ -210,10 +228,10 @@ in conjunction with the option:--tracefile-size option. 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 @@ -237,7 +255,7 @@ option:-u, option:--userspace:: 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. @@ -261,24 +279,12 @@ option:--num-subbuf='COUNT':: + 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'. @@ -293,6 +299,25 @@ Default values: * 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: @@ -315,7 +340,8 @@ Trace files ~~~~~~~~~~~ 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. + @@ -326,7 +352,7 @@ 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. + Default: {default_channel_tracefile_size}. + Note: traces generated with this option may inaccurately report discarded events as of CTF 1.8. @@ -334,29 +360,89 @@ 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)