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 Loading tracing session configurations
  65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  66 By default, the LTTng session daemon tries to load tracing session
  67 configurations located in the user default directory
  68 `$HOME/.lttng/sessions` and in the system one, +{system_sessions_dir}+.
  69 Note that both the directory containing the tracing session
  70 configurations and the session daemon binary _must_ have the same UID
  71 for the configurations to be automatically loaded.
  72
  73 Specifying a path with the option:--load option overrides the default
  74 directory _and_ the UID check. The session daemon simply checks if the
  75 path is accessible and tries to load every tracing session configuration
  76 in it.
  77
  78
  79 OPTIONS
  80 -------
  81 Daemon configuration
  82 ~~~~~~~~~~~~~~~~~~~~
  83 option:-b, option:--background::
  84     Start as Unix daemon, but keep file descriptors (console) open.
  85     Use the option:--daemonize option instead to close the file
  86     descriptors.
  87
  88 option:-d, option:--daemonize::
  89     Start as Unix daemon, and close file descriptors (console). Use the
  90     option:--background option instead to keep the file descriptors
  91     open.
  92
  93 option:-f, option:--config='PATH'::
  94     Load session daemon configuration from path 'PATH'.
  95
  96 option:-g, option:--group='GROUP'::
  97     Use 'GROUP' as Unix tracing group (default: `tracing`).
  98
  99 option:-l, option:--load='PATH'::
 100     Automatically load tracing session configurations from path 'PATH'.
 101
 102 option:-S, option:--sig-parent::
 103     Send `SIGUSR1` to parent process to notify readiness.
 104 +
 105 NOTE: This is used by man:lttng(1) to get notified when the
 106 session daemon is ready to accept commands. When building a third party
 107 tool on liblttng-ctl, this option can be very handy to synchronize the
 108 control tool and the session daemon.
 109
 110
 111 Linux kernel tracing
 112 ~~~~~~~~~~~~~~~~~~~~
 113 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
 114     Load specific LTTng Linux kernel modules when kernel tracing
 115     is enabled (option:--no-kernel option is :not: specified), in
 116     addition to loading the default list of LTTng kernel modules.
 117 +
 118 Only the name of the probe needs to be specified, without the
 119 `lttng-probe-` prefix and without the kernel module extension suffix.
 120 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
 121 module.
 122
 123 option:--kmod-probes='PROBE'[,'PROBE']...::
 124     Only load specific LTTng Linux kernel modules when kernel tracing
 125     is enabled (option:--no-kernel option is :not: specified).
 126 +
 127 Only the name of the probe needs to be specified, without the
 128 `lttng-probe-` prefix and without the kernel module extension suffix.
 129 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
 130 module.
 131
 132 option:--no-kernel::
 133     Disable Linux kernel tracing.
 134
 135
 136 Paths and ports
 137 ~~~~~~~~~~~~~~~
 138 option:--agent-tcp-port='PORT'::
 139     Listen on TCP port 'PORT' for agent application registrations
 140     (default: 5345).
 141
 142 option:-a, option:--apps-sock='PATH'::
 143     Set application Unix socket path to 'PATH'.
 144
 145 option:-c, option:--client-sock='PATH'::
 146     Set client Unix socket path to 'PATH'.
 147
 148 option:--consumerd32-libdir='PATH'::
 149     Set 32-bit consumer daemon library directory to 'PATH'.
 150
 151 option:--consumerd32-path='PATH'::
 152     Set 32-bit consumer daemon binary path to 'PATH'.
 153
 154 option:--consumerd64-libdir='PATH'::
 155     Set 64-bit consumer daemon library directory to 'PATH'.
 156
 157 option:--consumerd64-path='PATH'::
 158     Set 64-bit consumer daemon binary path to 'PATH'.
 159
 160 option:--kconsumerd-cmd-sock='PATH'::
 161     Set Linux kernel consumer daemon's command Unix socket path
 162     to 'PATH'.
 163
 164 option:--kconsumerd-err-sock='PATH'::
 165     Set Linux kernel consumer daemon's error Unix socket path
 166     to 'PATH'.
 167
 168 option:--ustconsumerd32-cmd-sock='PATH'::
 169     Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
 170
 171 option:--ustconsumerd64-cmd-sock='PATH'::
 172     Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
 173
 174 option:--ustconsumerd32-err-sock='PATH'::
 175     Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
 176
 177 option:--ustconsumerd64-err-sock='PATH'::
 178     Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
 179
 180
 181 Verbosity
 182 ~~~~~~~~~
 183 option:-q, option:--quiet::
 184     Suppress all messages, including warnings and errors.
 185
 186 option:-v, option:--verbose::
 187     Increase verbosity.
 188 +
 189 Three levels of verbosity are available, which are triggered by
 190 appending additional `v` letters to the option
 191 (that is, `-vv` and `-vvv`).
 192
 193 option:--verbose-consumer::
 194     Increase verbosity of consumer daemons spawned by this session
 195     daemon.
 196
 197
 198 Program information
 199 ~~~~~~~~~~~~~~~~~~~
 200 option:-h, option:--help::
 201     Show help.
 202
 203 option:-V, option:--version::
 204     Show version.
 205
 206
 207 ENVIRONMENT VARIABLES
 208 ---------------------
 209 Note that command-line options override their equivalent environment
 210 variable.
 211
 212 `LTTNG_APP_SOCKET_TIMEOUT`::
 213     Application socket's timeout (seconds) when sending/receiving
 214     commands. After this period of time, the application is unregistered
 215     by the session daemon. A value of 0 or -1 means an infinite timeout.
 216     Default value: 5.
 217
 218 `LTTNG_CONSUMERD32_BIN`::
 219     32-bit consumer daemon binary path.
 220 +
 221 The option:--consumerd32-path option overrides this variable.
 222
 223 `LTTNG_CONSUMERD32_LIBDIR`::
 224     32-bit consumer daemon library path.
 225 +
 226 The option:--consumerd32-libdir option overrides this variable.
 227
 228 `LTTNG_CONSUMERD64_BIN`::
 229     64-bit consumer daemon binary path.
 230 +
 231 The option:--consumerd64-path option overrides this variable.
 232
 233 `LTTNG_CONSUMERD64_LIBDIR`::
 234     64-bit consumer daemon library path.
 235 +
 236 The option:--consumerd64-libdir option overrides this variable.
 237
 238 `LTTNG_DEBUG_NOCLONE`::
 239     Set to 1 to disable the use of `clone()`/`fork()`. Setting this
 240     variable is considered insecure, but it is required to allow
 241     debuggers to work with the session daemon on some operating systems.
 242
 243 `LTTNG_EXTRA_KMOD_PROBES`::
 244     Load specific LTTng Linux kernel modules when kernel tracing
 245     is enabled (option:--no-kernel option is :not: specified), in
 246     addition to loading the default list of LTTng kernel modules.
 247 +
 248 The option:--extra-kmod-probes option overrides this variable.
 249
 250 `LTTNG_KMOD_PROBES`::
 251     Only load specific LTTng Linux kernel modules when kernel tracing
 252     is enabled (option:--no-kernel option is :not: specified).
 253 +
 254 The option:--kmod-probes option overrides this variable.
 255
 256 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 257     Socket connection, receive and send timeout (milliseconds). A value
 258     of 0 or -1 uses the timeout of the operating system (default).
 259
 260 `LTTNG_SESSION_CONFIG_XSD_PATH`::
 261     Tracing session configuration XML schema definition (XSD) path.
 262
 263
 264 FILES
 265 -----
 266 `$LTTNG_HOME/.lttng`::
 267     User LTTng runtime and configuration directory.
 268
 269 `$LTTNG_HOME/lttng-traces`::
 270     Default output directory of LTTng traces. This can be overridden
 271     with the nloption:--output option of the man:lttng-create(1)
 272     command.
 273
 274 `$LTTNG_HOME/.lttng/sessions`::
 275     Default location of saved user tracing sessions (see
 276     man:lttng-save(1) and man:lttng-load(1)).
 277
 278 +{system_sessions_dir}+::
 279     System-wide location of saved tracing sessions
 280     (see man:lttng-save(1) and man:lttng-load(1)).
 281
 282 `$LTTNG_HOME/.lttng/lttng.conf`::
 283     Default location of the session daemon configuration file (see the
 284     option:--config option).
 285
 286 +{system_lttng_conf}+::
 287     System-wide location of the session daemon configuration file (see
 288     the option:--config option).
 289
 290 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
 291
 292
 293 EXIT STATUS
 294 -----------
 295 *0*::
 296     Success
 297
 298 *1*::
 299     Error
 300
 301 *3*::
 302     Fatal error
 303
 304
 305 LIMITATIONS
 306 -----------
 307 For an unprivileged user running `lttng-sessiond`, the maximum number of
 308 file descriptors per process is usually 1024. This limits the number of
 309 traceable applications, since for each instrumented application, there
 310 is two file descriptors per CPU and one more socket for bidirectional
 311 communication.
 312
 313 For the root user, the limit is bumped to 65535. A future version will
 314 deal with this limitation.
 315
 316
 317 include::common-footer.txt[]
 318
 319
 320 SEE ALSO
 321 --------
 322 man:lttng(1),
 323 man:lttng-relayd(8),
 324 man:lttng-crash(1),
 325 man:lttng-ust(3),
 326 man:babeltrace(1)