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