doc/man/lttng-sessiond.8.txt

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