sessiond: split event notifier error counter CLI options

[lttng-tools.git] / doc / man / lttng-sessiond.8.txt

lttng-sessiond(8)
=================
:revdate: 17 September 2018


NAME
----
lttng-sessiond - LTTng 2 tracing session daemon


SYNOPSIS
--------
[verse]
*lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent]
               [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH']
               [option:--agent-tcp-port='PORT']
               [option:--apps-sock='PATH'] [option:--client-sock='PATH']
               [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...]
                              [option:--extra-kmod-probes='PROBE'[,'PROBE']...]
                              [option:--kconsumerd-err-sock='PATH']
                              [option:--kconsumerd-cmd-sock='PATH']]
               [option:--ustconsumerd32-err-sock='PATH']
               [option:--ustconsumerd64-err-sock='PATH']
               [option:--ustconsumerd32-cmd-sock='PATH']
               [option:--ustconsumerd64-cmd-sock='PATH']
               [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
               [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
               [option:--event-notifier-error-buffer-size-kernel='SIZE']
               [option:--event-notifier-error-buffer-size-userspace='SIZE']
               [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]


DESCRIPTION
-----------
The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
source software package used for correlated tracing of the Linux kernel,
user applications, and user libraries.

LTTng consists of Linux kernel modules (for Linux kernel tracing) and
dynamically loaded libraries (for user application and library tracing).

The _LTTng session daemon_ is a tracing registry which allows the user
to interact with multiple tracers (kernel and user space) within the
same container, a _tracing session_. Traces can be gathered from the
Linux kernel and/or from instrumented applications (see
man:lttng-ust(3)). You can aggregate and read the events of LTTng
traces using man:babeltrace2(1).

To trace the Linux kernel, the session daemon needs to be running as
`root`. LTTng uses a _tracing group_ to allow specific users to interact
with the root session daemon. The default tracing group name is
`tracing`. You can use the option:--group option to set the tracing
group name to use.

Session daemons can coexist. You can have a session daemon running as
user Alice that can be used to trace her applications alongside a root
session daemon or a session daemon running as user Bob.

The LTTng session daemon manages trace data consumer daemons by spawning
them when necessary. You do not need to manage the consumer daemons
manually.

NOTE: It is highly recommended to start the session daemon at boot time
for stable and long-term tracing.


Automatic loading of tracing session configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When the session daemon starts, it automatically loads session
configuration files.

The following directories are searched, non-recursively, in this order
for configuration files to load on launch:

. `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`)
. +{system_sessions_auto_dir}+

Note that both the directory containing the tracing session
configurations _and_ the session daemon binary _must_ share the same UID
for the configurations to be automatically loaded.

The option:--load option overrides the default directories _and_ the UID
check. The session daemon simply checks if the path is accessible and
tries to load every tracing session configuration in it. When this
option is specified, the default directories are :not: searched for
configuration files. When the option is not specified, _both_ default
directories are searched for configuration files.

If the option:--load option's argument is a directory, then all the
tracing session configurations found in all the files in this directory
are loaded. If the argument is a file, then all the tracing session
configurations found in this file are loaded.


OPTIONS
-------
Daemon configuration
~~~~~~~~~~~~~~~~~~~~
option:-b, option:--background::
    Start as Unix daemon, but keep file descriptors (console) open.
    Use the option:--daemonize option instead to close the file
    descriptors.

option:-f 'PATH', option:--config='PATH'::
    Load session daemon configuration from path 'PATH'.

option:-d, option:--daemonize::
    Start as Unix daemon, and close file descriptors (console). Use the
    option:--background option instead to keep the file descriptors
    open.

option:-g 'GROUP', option:--group='GROUP'::
    Use 'GROUP' as Unix tracing group (default: `tracing`).

option:-l 'PATH', option:--load='PATH'::
    Automatically load tracing session configurations from 'PATH',
    either a directory or a file, instead of loading them from the
    default search directories.

option:-S, option:--sig-parent::
    Send `SIGUSR1` to parent process to notify readiness.
+
NOTE: This is used by man:lttng(1) to get notified when the
session daemon is ready to accept commands. When building a third party
tool on liblttng-ctl, this option can be very handy to synchronize the
control tool and the session daemon.

option:--event-notifier-error-buffer-size-kernel='SIZE'::
    Set the size of the kernel event notifier error counter buffers to 'SIZE.

option:--event-notifier-error-buffer-size-userspace='SIZE'::
    Set the size of the userspace event notifier error counter buffers to
    'SIZE.


Linux kernel tracing
~~~~~~~~~~~~~~~~~~~~
option:--extra-kmod-probes='PROBE'[,'PROBE']...::
    Load specific LTTng Linux kernel modules when kernel tracing
    is enabled (option:--no-kernel option is :not: specified), in
    addition to loading the default list of LTTng kernel modules.
+
Only the name of the probe needs to be specified, without the
`lttng-probe-` prefix and without the kernel module extension suffix.
For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
module.

option:--kmod-probes='PROBE'[,'PROBE']...::
    Only load specific LTTng Linux kernel modules when kernel tracing
    is enabled (option:--no-kernel option is :not: specified).
+
Only the name of the probe needs to be specified, without the
`lttng-probe-` prefix and without the kernel module extension suffix.
For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
module.

option:--no-kernel::
    Disable Linux kernel tracing.


Paths and ports
~~~~~~~~~~~~~~~
option:--agent-tcp-port='PORT'::
    Listen on TCP port 'PORT' for agent application registrations
    (default: a port within the range
    [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).

option:-a 'PATH', option:--apps-sock='PATH'::
    Set application Unix socket path to 'PATH'.

option:-c 'PATH', option:--client-sock='PATH'::
    Set client Unix socket path to 'PATH'.

option:--consumerd32-libdir='PATH'::
    Set 32-bit consumer daemon library directory to 'PATH'.

option:--consumerd32-path='PATH'::
    Set 32-bit consumer daemon binary path to 'PATH'.

option:--consumerd64-libdir='PATH'::
    Set 64-bit consumer daemon library directory to 'PATH'.

option:--consumerd64-path='PATH'::
    Set 64-bit consumer daemon binary path to 'PATH'.

option:--kconsumerd-cmd-sock='PATH'::
    Set Linux kernel consumer daemon's command Unix socket path
    to 'PATH'.

option:--kconsumerd-err-sock='PATH'::
    Set Linux kernel consumer daemon's error Unix socket path
    to 'PATH'.

option:--ustconsumerd32-cmd-sock='PATH'::
    Set 32-bit consumer daemon's command Unix socket path to 'PATH'.

option:--ustconsumerd64-cmd-sock='PATH'::
    Set 64-bit consumer daemon's command Unix socket path to 'PATH'.

option:--ustconsumerd32-err-sock='PATH'::
    Set 32-bit consumer daemon's error Unix socket path to 'PATH'.

option:--ustconsumerd64-err-sock='PATH'::
    Set 64-bit consumer daemon's error Unix socket path to 'PATH'.


Verbosity
~~~~~~~~~
option:-q, option:--quiet::
    Suppress all messages, including warnings and errors.

option:-v, option:--verbose::
    Increase verbosity.
+
Three levels of verbosity are available, which are triggered by
appending additional `v` letters to the option
(that is, `-vv` and `-vvv`).

option:--verbose-consumer::
    Increase verbosity of consumer daemons spawned by this session
    daemon.


Program information
~~~~~~~~~~~~~~~~~~~
option:-h, option:--help::
    Show help.

option:-V, option:--version::
    Show version.


ENVIRONMENT VARIABLES
---------------------
Note that command-line options override their equivalent environment
variable.

`LTTNG_ABORT_ON_ERROR`::
    Set to 1 to abort the process after the first error is encountered.

`LTTNG_APP_SOCKET_TIMEOUT`::
    Application socket's timeout (seconds) when sending/receiving
    commands. After this period of time, the application is unregistered
    by the session daemon. A value of 0 or -1 means an infinite timeout.
    Default value: {default_app_socket_rw_timeout}.

`LTTNG_CONSUMERD32_BIN`::
    32-bit consumer daemon binary path.
+
The option:--consumerd32-path option overrides this variable.

`LTTNG_CONSUMERD32_LIBDIR`::
    32-bit consumer daemon library path.
+
The option:--consumerd32-libdir option overrides this variable.

`LTTNG_CONSUMERD64_BIN`::
    64-bit consumer daemon binary path.
+
The option:--consumerd64-path option overrides this variable.

`LTTNG_CONSUMERD64_LIBDIR`::
    64-bit consumer daemon library path.
+
The option:--consumerd64-libdir option overrides this variable.

`LTTNG_DEBUG_NOCLONE`::
    Set to 1 to disable the use of `clone()`/`fork()`. Setting this
    variable is considered insecure, but it is required to allow
    debuggers to work with the session daemon on some operating systems.

`LTTNG_EXTRA_KMOD_PROBES`::
    Load specific LTTng Linux kernel modules when kernel tracing
    is enabled (option:--no-kernel option is :not: specified), in
    addition to loading the default list of LTTng kernel modules.
+
The option:--extra-kmod-probes option overrides this variable.

`LTTNG_KMOD_PROBES`::
    Only load specific LTTng Linux kernel modules when kernel tracing
    is enabled (option:--no-kernel option is :not: specified).
+
The option:--kmod-probes option overrides this variable.

`LTTNG_NETWORK_SOCKET_TIMEOUT`::
    Socket connection, receive and send timeout (milliseconds). A value
    of 0 or -1 uses the timeout of the operating system (default).

`LTTNG_SESSION_CONFIG_XSD_PATH`::
    Tracing session configuration XML schema definition (XSD) path.


FILES
-----
`$LTTNG_HOME/.lttng`::
    User LTTng runtime and configuration directory.

`$LTTNG_HOME/lttng-traces`::
    Default output directory of LTTng traces. This can be overridden
    with the nloption:--output option of the man:lttng-create(1)
    command.

`$LTTNG_HOME/.lttng/sessions/auto`::
    Directory from which user tracing configuration files are
    automatically loaded when the session daemon starts (see
    man:lttng-save(1) and man:lttng-load(1) for saving
    and loading tracing sessions).

+{system_sessions_auto_dir}+::
    Directory from which system-wide tracing configuration files are
    automatically loaded when the session daemon starts (see
    man:lttng-save(1) and man:lttng-load(1) for saving
    and loading tracing sessions).

`$LTTNG_HOME/.lttng/lttng.conf`::
    Default location of the session daemon configuration file (see the
    option:--config option).

+{system_lttng_conf}+::
    System-wide location of the session daemon configuration file (see
    the option:--config option).

NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.


EXIT STATUS
-----------
*0*::
    Success

*1*::
    Error

*3*::
    Fatal error


LIMITATIONS
-----------
For an unprivileged user running `lttng-sessiond`, the maximum number of
file descriptors per process is usually 1024. This limits the number of
traceable applications, since for each instrumented application, there
is two file descriptors per CPU and one more socket for bidirectional
communication.

For the root user, the limit is bumped to 65535. A future version will
deal with this limitation.


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-relayd(8),
man:lttng-crash(1),
man:lttng-ust(3),
man:babeltrace2(1)