lttng-enable-channel(1): add usage examples

[lttng-tools.git] / doc / man / lttng-enable-channel.1.txt

lttng-enable-channel(1)
=======================
:revdate: 17 May 2021


NAME
----
lttng-enable-channel - Create or enable LTTng channels


SYNOPSIS
--------
Create a Linux kernel channel:

[verse]
*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:--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* ['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:--monitor-timer='PERIODUS']
      [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
      [option:--session='SESSION'] 'CHANNEL'

Enable channel(s):

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
      [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...


DESCRIPTION
-----------
The `lttng enable-channel` command does one of:

* Create a channel named 'CHANNEL'.

* Enable one or more disabled channels named 'CHANNEL'
  (non-option argument, comma-separated).

See man:lttng-concepts(7) to learn more about channels.

The channel(s) to create or enable belong to:

With the option:--session='SESSION' option::
    The tracing session named 'SESSION'.

Without the option:--session option::
    The current tracing session (see man:lttng-concepts(7) to learn more
    about the current tracing session).

NOTE: The man:lttng-enable-event(1) command can automatically create a
default channel when no channel exists for the provided tracing domain.

See the <<examples,EXAMPLES>> section below for usage examples.

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.

[IMPORTANT]
====
As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
operations with the `enable-channel` command:

* Change an attribute of an existing channel.

* Enable a disabled channel once its tracing session has been active
  (started; see man:lttng-start(1)) 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-lttng-cmd-options-head.txt[]


Tracing domain
~~~~~~~~~~~~~~
One of:

option:-k, option:--kernel::
    Create or enable channels in the Linux kernel domain.

option:-u, option:--userspace::
    Create or enable channels in the user space domain.


Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Create or enable channels in the tracing session named 'SESSION'
    instead of the current tracing session.


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 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::
    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 per ring buffer.
+
The effective value is 'COUNT' rounded up to the next power of two.
+
Default values:
+
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:--output='TYPE'::
    Set channel's output type to 'TYPE'.
+
'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:::
    `mmap`
option:--userspace and option:--buffers-pid options:::
    `mmap`
option:--kernel and option:--buffers-global options:::
    `splice`
`metadata` channel:::
    `mmap`

option:--subbuf-size='SIZE'::
    Set the size of each sub-buffer to 'SIZE' bytes.
+
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:::
    +{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 which LTTng writes for this channel
    to 'COUNT'.
+
'COUNT' set to `0` means ``unlimited''.
+
Default: +{default_channel_tracefile_count}+.
+
You must also use the option:--tracefile-size option with this option.

option:--tracefile-size='SIZE'::
    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: 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:--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:::
    +{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 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-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.Create a Linux kernel channel with default attributes in the current tracing session.
====
The following command line only creates a new channel if `my-channel`
doesn't name an existing Linux kernel channel in the current tracing
session.

[role="term"]
----
$ lttng enable-channel --kernel my-channel
----
====

.Create a user space channel with a per-process buffering scheme in a specific tracing session.
====
See the option:--session and option:--buffers-pid options.

[role="term"]
----
$ lttng enable-channel --session=my-session --userspace \
                       --buffers-pid my-channel
----
====

.Create a Linux kernel channel in the current tracing session with four 32-MiB sub-buffers per ring buffer.
====
See the option:--num-subbuf and option:--subbuf-size options.

[role="term"]
----
$ lttng enable-channel --kernel my-channel \
                       --num-subbuf=4 --subbuf-size=32M
----
====

.Create a user space channel in the current tracing session with trace file rotation.
====
See the option:--tracefile-count and option:--tracefile-size options.

[role="term"]
----
$ lttng enable-channel --userspace my-channel \
                       --tracefile-count=16 --tracefile-size=8M
----
====

.Enable two user space channels of a specific tracing session.
====
[role="term"]
----
$ lttng enable-channel --session=my-session --userspace \
                       canal-d,rds
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-disable-channel(1),
man:lttng-list(1),
man:lttng-concepts(7)