doc/man/lttng-sessiond.8.txt

   1 lttng-sessiond(8)
   2 =================
   3 :revdate: 17 September 2018
   4
   5
   6 NAME
   7 ----
   8 lttng-sessiond - LTTng 2 tracing session daemon
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent]
  15                [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH']
  16                [option:--agent-tcp-port='PORT']
  17                [option:--apps-sock='PATH'] [option:--client-sock='PATH']
  18                [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...]
  19                               [option:--extra-kmod-probes='PROBE'[,'PROBE']...]
  20                               [option:--kconsumerd-err-sock='PATH']
  21                               [option:--kconsumerd-cmd-sock='PATH']]
  22                [option:--ustconsumerd32-err-sock='PATH']
  23                [option:--ustconsumerd64-err-sock='PATH']
  24                [option:--ustconsumerd32-cmd-sock='PATH']
  25                [option:--ustconsumerd64-cmd-sock='PATH']
  26                [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
  27                [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
  28                [option:--event-notifier-error-buffer-size-kernel='SIZE']
  29                [option:--event-notifier-error-buffer-size-userspace='SIZE']
  30                [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]
  31
  32
  33 DESCRIPTION
  34 -----------
  35 The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
  36 source software package used for correlated tracing of the Linux kernel,
  37 user applications, and user libraries.
  38
  39 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
  40 dynamically loaded libraries (for user application and library tracing).
  41
  42 The _LTTng session daemon_ is a tracing registry which allows the user
  43 to interact with multiple tracers (kernel and user space) within the
  44 same container, a _tracing session_. Traces can be gathered from the
  45 Linux kernel and/or from instrumented applications (see
  46 man:lttng-ust(3)). You can aggregate and read the events of LTTng
  47 traces using man:babeltrace2(1).
  48
  49 To trace the Linux kernel, the session daemon needs to be running as
  50 `root`. LTTng uses a _tracing group_ to allow specific users to interact
  51 with the root session daemon. The default tracing group name is
  52 `tracing`. You can use the option:--group option to set the tracing
  53 group name to use.
  54
  55 Session daemons can coexist. You can have a session daemon running as
  56 user Alice that can be used to trace her applications alongside a root
  57 session daemon or a session daemon running as user Bob.
  58
  59 The LTTng session daemon manages trace data consumer daemons by spawning
  60 them when necessary. You do not need to manage the consumer daemons
  61 manually.
  62
  63 NOTE: It is highly recommended to start the session daemon at boot time
  64 for stable and long-term tracing.
  65
  66
  67 Automatic loading of tracing session configurations
  68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  69 When the session daemon starts, it automatically loads session
  70 configuration files.
  71
  72 The following directories are searched, non-recursively, in this order
  73 for configuration files to load on launch:
  74
  75 . `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`)
  76 . +{system_sessions_auto_dir}+
  77
  78 Note that both the directory containing the tracing session
  79 configurations _and_ the session daemon binary _must_ share the same UID
  80 for the configurations to be automatically loaded.
  81
  82 The option:--load option overrides the default directories _and_ the UID
  83 check. The session daemon simply checks if the path is accessible and
  84 tries to load every tracing session configuration in it. When this
  85 option is specified, the default directories are :not: searched for
  86 configuration files. When the option is not specified, _both_ default
  87 directories are searched for configuration files.
  88
  89 If the option:--load option's argument is a directory, then all the
  90 tracing session configurations found in all the files in this directory
  91 are loaded. If the argument is a file, then all the tracing session
  92 configurations found in this file are loaded.
  93
  94
  95 OPTIONS
  96 -------
  97 Daemon configuration
  98 ~~~~~~~~~~~~~~~~~~~~
  99 option:-b, option:--background::
 100     Start as Unix daemon, but keep file descriptors (console) open.
 101     Use the option:--daemonize option instead to close the file
 102     descriptors.
 103
 104 option:-f 'PATH', option:--config='PATH'::
 105     Load session daemon configuration from path 'PATH'.
 106
 107 option:-d, option:--daemonize::
 108     Start as Unix daemon, and close file descriptors (console). Use the
 109     option:--background option instead to keep the file descriptors
 110     open.
 111
 112 option:-g 'GROUP', option:--group='GROUP'::
 113     Use 'GROUP' as Unix tracing group (default: `tracing`).
 114
 115 option:-l 'PATH', option:--load='PATH'::
 116     Automatically load tracing session configurations from 'PATH',
 117     either a directory or a file, instead of loading them from the
 118     default search directories.
 119
 120 option:-S, option:--sig-parent::
 121     Send `SIGUSR1` to parent process to notify readiness.
 122 +
 123 NOTE: This is used by man:lttng(1) to get notified when the
 124 session daemon is ready to accept commands. When building a third party
 125 tool on liblttng-ctl, this option can be very handy to synchronize the
 126 control tool and the session daemon.
 127
 128 option:--event-notifier-error-buffer-size-kernel='SIZE'::
 129     Set the size of the kernel event notifier error counter buffers to 'SIZE.
 130
 131 option:--event-notifier-error-buffer-size-userspace='SIZE'::
 132     Set the size of the userspace event notifier error counter buffers to
 133     'SIZE.
 134
 135
 136 Linux kernel tracing
 137 ~~~~~~~~~~~~~~~~~~~~
 138 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
 139     Load specific LTTng Linux kernel modules when kernel tracing
 140     is enabled (option:--no-kernel option is :not: specified), in
 141     addition to loading the default list of LTTng kernel modules.
 142 +
 143 Only the name of the probe needs to be specified, without the
 144 `lttng-probe-` prefix and without the kernel module extension suffix.
 145 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
 146 module.
 147
 148 option:--kmod-probes='PROBE'[,'PROBE']...::
 149     Only load specific LTTng Linux kernel modules when kernel tracing
 150     is enabled (option:--no-kernel option is :not: specified).
 151 +
 152 Only the name of the probe needs to be specified, without the
 153 `lttng-probe-` prefix and without the kernel module extension suffix.
 154 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
 155 module.
 156
 157 option:--no-kernel::
 158     Disable Linux kernel tracing.
 159
 160
 161 Paths and ports
 162 ~~~~~~~~~~~~~~~
 163 option:--agent-tcp-port='PORT'::
 164     Listen on TCP port 'PORT' for agent application registrations
 165     (default: a port within the range
 166     [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
 167
 168 option:-a 'PATH', option:--apps-sock='PATH'::
 169     Set application Unix socket path to 'PATH'.
 170
 171 option:-c 'PATH', option:--client-sock='PATH'::
 172     Set client Unix socket path to 'PATH'.
 173
 174 option:--consumerd32-libdir='PATH'::
 175     Set 32-bit consumer daemon library directory to 'PATH'.
 176
 177 option:--consumerd32-path='PATH'::
 178     Set 32-bit consumer daemon binary path to 'PATH'.
 179
 180 option:--consumerd64-libdir='PATH'::
 181     Set 64-bit consumer daemon library directory to 'PATH'.
 182
 183 option:--consumerd64-path='PATH'::
 184     Set 64-bit consumer daemon binary path to 'PATH'.
 185
 186 option:--kconsumerd-cmd-sock='PATH'::
 187     Set Linux kernel consumer daemon's command Unix socket path
 188     to 'PATH'.
 189
 190 option:--kconsumerd-err-sock='PATH'::
 191     Set Linux kernel consumer daemon's error Unix socket path
 192     to 'PATH'.
 193
 194 option:--ustconsumerd32-cmd-sock='PATH'::
 195     Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
 196
 197 option:--ustconsumerd64-cmd-sock='PATH'::
 198     Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
 199
 200 option:--ustconsumerd32-err-sock='PATH'::
 201     Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
 202
 203 option:--ustconsumerd64-err-sock='PATH'::
 204     Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
 205
 206
 207 Verbosity
 208 ~~~~~~~~~
 209 option:-q, option:--quiet::
 210     Suppress all messages, including warnings and errors.
 211
 212 option:-v, option:--verbose::
 213     Increase verbosity.
 214 +
 215 Three levels of verbosity are available, which are triggered by
 216 appending additional `v` letters to the option
 217 (that is, `-vv` and `-vvv`).
 218
 219 option:--verbose-consumer::
 220     Increase verbosity of consumer daemons spawned by this session
 221     daemon.
 222
 223
 224 Program information
 225 ~~~~~~~~~~~~~~~~~~~
 226 option:-h, option:--help::
 227     Show help.
 228
 229 option:-V, option:--version::
 230     Show version.
 231
 232
 233 ENVIRONMENT VARIABLES
 234 ---------------------
 235 Note that command-line options override their equivalent environment
 236 variable.
 237
 238 `LTTNG_ABORT_ON_ERROR`::
 239     Set to 1 to abort the process after the first error is encountered.
 240
 241 `LTTNG_APP_SOCKET_TIMEOUT`::
 242     Application socket's timeout (seconds) when sending/receiving
 243     commands. After this period of time, the application is unregistered
 244     by the session daemon. A value of 0 or -1 means an infinite timeout.
 245     Default value: {default_app_socket_rw_timeout}.
 246
 247 `LTTNG_CONSUMERD32_BIN`::
 248     32-bit consumer daemon binary path.
 249 +
 250 The option:--consumerd32-path option overrides this variable.
 251
 252 `LTTNG_CONSUMERD32_LIBDIR`::
 253     32-bit consumer daemon library path.
 254 +
 255 The option:--consumerd32-libdir option overrides this variable.
 256
 257 `LTTNG_CONSUMERD64_BIN`::
 258     64-bit consumer daemon binary path.
 259 +
 260 The option:--consumerd64-path option overrides this variable.
 261
 262 `LTTNG_CONSUMERD64_LIBDIR`::
 263     64-bit consumer daemon library path.
 264 +
 265 The option:--consumerd64-libdir option overrides this variable.
 266
 267 `LTTNG_DEBUG_NOCLONE`::
 268     Set to 1 to disable the use of `clone()`/`fork()`. Setting this
 269     variable is considered insecure, but it is required to allow
 270     debuggers to work with the session daemon on some operating systems.
 271
 272 `LTTNG_EXTRA_KMOD_PROBES`::
 273     Load specific LTTng Linux kernel modules when kernel tracing
 274     is enabled (option:--no-kernel option is :not: specified), in
 275     addition to loading the default list of LTTng kernel modules.
 276 +
 277 The option:--extra-kmod-probes option overrides this variable.
 278
 279 `LTTNG_KMOD_PROBES`::
 280     Only load specific LTTng Linux kernel modules when kernel tracing
 281     is enabled (option:--no-kernel option is :not: specified).
 282 +
 283 The option:--kmod-probes option overrides this variable.
 284
 285 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 286     Socket connection, receive and send timeout (milliseconds). A value
 287     of 0 or -1 uses the timeout of the operating system (default).
 288
 289 `LTTNG_SESSION_CONFIG_XSD_PATH`::
 290     Tracing session configuration XML schema definition (XSD) path.
 291
 292
 293 FILES
 294 -----
 295 `$LTTNG_HOME/.lttng`::
 296     User LTTng runtime and configuration directory.
 297
 298 `$LTTNG_HOME/lttng-traces`::
 299     Default output directory of LTTng traces. This can be overridden
 300     with the nloption:--output option of the man:lttng-create(1)
 301     command.
 302
 303 `$LTTNG_HOME/.lttng/sessions/auto`::
 304     Directory from which user tracing configuration files are
 305     automatically loaded when the session daemon starts (see
 306     man:lttng-save(1) and man:lttng-load(1) for saving
 307     and loading tracing sessions).
 308
 309 +{system_sessions_auto_dir}+::
 310     Directory from which system-wide tracing configuration files are
 311     automatically loaded when the session daemon starts (see
 312     man:lttng-save(1) and man:lttng-load(1) for saving
 313     and loading tracing sessions).
 314
 315 `$LTTNG_HOME/.lttng/lttng.conf`::
 316     Default location of the session daemon configuration file (see the
 317     option:--config option).
 318
 319 +{system_lttng_conf}+::
 320     System-wide location of the session daemon configuration file (see
 321     the option:--config option).
 322
 323 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
 324
 325
 326 EXIT STATUS
 327 -----------
 328 *0*::
 329     Success
 330
 331 *1*::
 332     Error
 333
 334 *3*::
 335     Fatal error
 336
 337
 338 LIMITATIONS
 339 -----------
 340 For an unprivileged user running `lttng-sessiond`, the maximum number of
 341 file descriptors per process is usually 1024. This limits the number of
 342 traceable applications, since for each instrumented application, there
 343 is two file descriptors per CPU and one more socket for bidirectional
 344 communication.
 345
 346 For the root user, the limit is bumped to 65535. A future version will
 347 deal with this limitation.
 348
 349
 350 include::common-footer.txt[]
 351
 352
 353 SEE ALSO
 354 --------
 355 man:lttng(1),
 356 man:lttng-relayd(8),
 357 man:lttng-crash(1),
 358 man:lttng-ust(3),
 359 man:babeltrace2(1)