X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-channel.1.txt;h=271ada1ceb3b0bebb3407b039bda57f7fbc9e8ec;hb=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66;hp=b5e7c947d20eda9c65bfd5dc75c96ab309353146;hpb=d4f093aa457acf5492c099f40badcc8379c95fe9;p=lttng-tools.git diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index b5e7c947d..271ada1ce 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -1,5 +1,6 @@ lttng-enable-channel(1) ======================= +:revdate: 3 May 2021 NAME @@ -12,342 +13,336 @@ 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:--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:--monitor-timer='PERIODUS'] [option:--buffers-global] + [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:--discard] option:--blocking-timeout='TIMEOUTUS'] + [option:--output=**mmap**] [option:--buffers-uid | 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:--monitor-timer='PERIODUS'] + [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']] [option:--session='SESSION'] 'CHANNEL' -Enable existing channel(s): +Enable 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']... 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. +The `lttng enable-channel` command does one of: -It's also convenient when big sub-buffers are used to cope with sporadic -high event throughput, even if the throughput is normally lower. +* Create a channel named 'CHANNEL'. -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. +* Enable one or more disabled channels named 'CHANNEL' + (non-option argument, comma-separated). +See man:lttng-concepts(7) to learn more about channels. -Buffering scheme -~~~~~~~~~~~~~~~~ -In the user space tracing domain, two buffering schemes are available -when creating a channel: +The channel(s) to create or enable belong to: -Per-process buffering (option:--buffers-pid option):: - Keep one ring buffer per process. +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -Per-user buffering (option:--buffers-uid option):: - Keep one ring buffer for all the processes of a single user. +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -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. +NOTE: The man:lttng-enable-event(1) command can automatically create a +default channel when no channel exists for the provided tracing domain. -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). +List the channels of a given tracing session with the +man:lttng-list(1) and man:lttng-status(1) commands. +Disable an enabled channel with the man:lttng-disable-channel(1) +command. -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. +[IMPORTANT] +==== +As of LTTng{nbsp}{lttng_version}, you may :not: perform the following +operations with the `enable-channel` command: -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. +* Change an attribute of an existing channel. -For example, consider this command: +* Enable a disabled channel once its tracing session has been active + (started; see man:lttng-start(1)) at least once. -[role="term"] ------------------------------------------------------ -lttng enable-channel --kernel --tracefile-size=4096 \ - --tracefile-count=32 my-channel ------------------------------------------------------ +* Create a channel once its tracing session has been active at least + once. -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. +* 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-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-k, option:--kernel:: - Enable channel in the Linux kernel domain. + Create or enable channels in the Linux kernel domain. option:-u, option:--userspace:: - Enable channel in the user space domain. + Create or enable channels in the user space domain. -Target -~~~~~~ -option:-s, option:--session='SESSION':: - Create or enable channel in the tracing session named 'SESSION' +Recording target +~~~~~~~~~~~~~~~~ +option:-s 'SESSION', option:--session='SESSION':: + Create or enable channels in the tracing session named 'SESSION' instead of the current tracing session. -Event loss mode -~~~~~~~~~~~~~~~ +Buffering scheme +~~~~~~~~~~~~~~~~ +One of: + +option:--buffers-global:: + Allocate a single set of ring buffers for the whole system. ++ +Only available with the option:--kernel option. ++ +As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme +for the Linux kernel tracing domain, but this may change in the future. + +option:--buffers-pid:: + Allocate one set of ring buffers (one per CPU) for each instrumented + process of: ++ +-- +If you connect to the root session daemon:: + All Unix users. ++ +See the ``Session daemon connection'' section of man:lttng(1) to learn +how a user application connects to a session daemon. + +Otherwise:: + Your Unix user. +-- ++ +Only available with the option:--userspace option. + +option:--buffers-uid:: + Allocate one set of ring buffers (one per CPU) shared by all the + instrumented processes of: ++ +-- +If you connect to the root session daemon:: + Each Unix user. ++ +See the ``Session daemon connection'' section of man:lttng(1) to learn +how a user application connects to a session daemon. + +Otherwise:: + Your Unix user. +-- ++ +Only available with the option:--userspace option. ++ +As of LTTng{nbsp}{lttng_version}, this is the default buffering scheme +for the user space tracing domain, but this may change in the future. + + +Event record loss mode +~~~~~~~~~~~~~~~~~~~~~~ +option:--blocking-timeout='TIMEOUTUS':: + Set the channel's blocking timeout value to __TIMEOUTUS__{nbsp}µs + for instrumented applications executed with a set + `LTTNG_UST_ALLOW_BLOCKING` environment variable. ++ +'TIMEOUTUS' is one of: ++ +-- +`0` (default):: + Do not block (non-blocking mode). + +`inf`:: + Block forever until a sub-buffer is available to write the event + record. + +__N__, a positive value:: + Wait for at most __N__{nbsp}µs when trying to write to a sub-buffer. + After __N__{nbsp}µs, discard the event record. +-- ++ +This option is only available with both the option:--userspace and +option:--discard options. + One of: option:--discard:: - Discard events when sub-buffers are full (default). + Discard event records when there's no available sub-buffer. ++ +As of LTTng{nbsp}{lttng_version}, this is the default event record loss +mode, but this may change in the future. option:--overwrite:: - Flight recorder mode: always keep a fixed amount of the latest - data. + Overwrite the whole sub-buffer containing the oldest event records + when there's no available sub-buffer (flight recorder mode). Sub-buffers ~~~~~~~~~~~ option:--num-subbuf='COUNT':: - Use 'COUNT' sub-buffers. Rounded up to the next power of two. + Use 'COUNT' sub-buffers per ring buffer. ++ +The effective value is 'COUNT' rounded up to the next power of two. + Default values: + -* `metadata` channel: 2 -* Everything else: 4 +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 and option:--buffers-global options::: + +{default_kernel_channel_subbuf_num}+ +`metadata` channel::: + +{default_metadata_subbuf_num}+ -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. +option:--output='TYPE':: + Set channel's output type to 'TYPE'. + -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`. +'TYPE' is one of: ++ +-- +`mmap`::: + Share ring buffers between the tracer and the consumer daemon with + the man:mmap(2) system call. + +`splice`::: + Share ring buffers between the tracer and the consumer daemon + with the man:splice(2) system call. ++ +Only available with the option:--kernel option. +-- + 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::: + `mmap` +option:--userspace and option:--buffers-pid options::: + `mmap` +option:--kernel and option:--buffers-global options::: + `splice` +`metadata` channel::: + `mmap` -option:--output='TYPE':: - Set channel's output type to 'TYPE'. +option:--subbuf-size='SIZE':: + Set the size of each sub-buffer to 'SIZE' bytes. + -Available types: `mmap` (always available) and `splice` (only available -with the option:--kernel option). +The effective value is 'SIZE' rounded up to the next power of two. ++ +The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are +supported. ++ +The minimum sub-buffer size, for each tracer, is the maximum value +between the default below and the system page size (see man:getconf(1) +with the `PAGE_SIZE` variable). + 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). +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 and option:--buffers-global options::: + +{default_kernel_channel_subbuf_size}+ +`metadata` channel::: + +{default_metadata_subbuf_size}+ Trace files ~~~~~~~~~~~ option:--tracefile-count='COUNT':: - Limit the number of trace files created by this channel to - 'COUNT'. 0 means unlimited. Default: 0. + Limit the number of trace files which LTTng writes for this channel + to 'COUNT'. ++ +'COUNT' set to `0` means ``unlimited''. + -Use this option in conjunction with the option:--tracefile-size option. +Default: +{default_channel_tracefile_count}+. + -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. +You must also use the option:--tracefile-size option with this 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. + Set the maximum size of each trace file which LTTng writes for + this channel to __SIZE__{nbsp}bytes. ++ +'SIZE' set to `0` means ``unlimited''. ++ +Default: +{default_channel_tracefile_size}+. + -Note: traces generated with this option may inaccurately report -discarded events as of CTF 1.8. +NOTE: Data streams which LTTng writes for a channel configured with this +option may inaccurately report discarded event records as of +CTF{nbsp}1.8. Timers ~~~~~~ -option:--read-timer:: - Set the channel's read timer's period to 'PERIODUS' µs. 0 means a - disabled read timer. +option:--monitor-timer='PERIODUS':: + Set the period of the monitor timer of the channel to + __PERIODUS__{nbsp}µs. ++ +Set 'PERIODUS' to `0` to disable the 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 and option:--buffers-global options::: + +{default_kernel_channel_monitor_timer}+ + +option:--read-timer='PERIODUS':: + Set the period of the read timer of the channel to + __PERIODUS__{nbsp}µs. ++ +Set 'PERIODUS' to `0` to disable the 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 and option:--buffers-global options::: + +{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. + Set the period of the switch timer of the channel to + __PERIODUS__{nbsp}µs. ++ +Set 'PERIODUS' to `0` to disable the 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 and option:--buffers-global options::: + +{default_kernel_channel_switch_timer}+ +`metadata` channel::: + +{default_metadata_switch_timer}+ include::common-cmd-help-options.txt[] @@ -358,5 +353,7 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -linklttng:lttng-disable-channel(1), -linklttng:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-disable-channel(1), +man:lttng-list(1)