doc/man/lttng-sessiond.8.txt

   1 lttng-sessiond(8)
   2 =================
   3 :revdate: 21 April 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-sessiond - LTTng 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='SLOTS']
  29                [option:--event-notifier-error-buffer-size-userspace='SLOTS']
  30                [option:--quiet | [option:--verbose]... [option:--verbose-consumer]]
  31
  32
  33 DESCRIPTION
  34 -----------
  35 include::common-intro.txt[]
  36
  37 An LTTng session daemon, `lttng-sessiond`, is a program which:
  38
  39 * Manages tracing sessions (see man:lttng-create(1) to learn more about
  40   tracing sessions).
  41
  42 * Controls the various components (like tracers and consumer daemons) of
  43   LTTng.
  44
  45 * Sends asynchronous notifications to user applications.
  46
  47 A session daemon receives commands from the man:lttng(1) command-line
  48 tool, as well as from any user application linked with the LTTng control
  49 library (`liblttng-ctl`).
  50
  51 Each Unix user may have its own independent running session daemon.
  52 However, the man:lttng(1) tool must connect to the session daemon of the
  53 `root` user (the root session daemon) to control Linux kernel tracing.
  54
  55 When you start `lttng-sessiond` as the `root` Unix user, a non-root Unix
  56 user can connect to it if it's part of the Unix tracing group. By
  57 default, the name of the tracing group is `tracing`. Override the
  58 tracing group name with the option:--group option.
  59
  60 See the ``Session daemon connection'' section of man:lttng(1) to learn
  61 how a user application connects to a session daemon.
  62
  63 A session daemon manages trace data consumer daemons, spawning them when
  64 necessary. You do :not: need to manage the consumer daemons yourself.
  65
  66 By default, `lttng-sessiond` doesn't start as a daemon. Make it a daemon
  67 with the option:--daemonize or option:--background option. With those
  68 options, `lttng-sessiond` ensures the daemon is ready to receive client
  69 commands before it exits.
  70
  71 NOTE: The LTTng project recommends that you start the session daemon at
  72 boot time for stable and long-term tracing.
  73
  74
  75 [[cfg]]
  76 Daemon configuration
  77 ~~~~~~~~~~~~~~~~~~~~
  78 When you run `lttng-sessiond`, it configures itself from, in this order:
  79
  80 . The INI configuration file +{system_lttng_conf}+, if any.
  81
  82 . The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any.
  83 +
  84 `$LTTNG_HOME` defaults to `$HOME`.
  85
  86 . With the option:--config='PATH' option: the INI configuration file
  87   'PATH'.
  88
  89 . The command-line options.
  90
  91 Each step can override a previous configuration property.
  92
  93 In INI configuration files, the session daemon only reads the properties
  94 under the `sessiond` INI section. Each INI property is:
  95
  96 Key::
  97     The long name of a command-line option to set (see the
  98     <<options,OPTIONS>> section below).
  99
 100 Value::
 101     The selected command-line option accepts an argument:::
 102         Option argument (string).
 103
 104     The selected command-line option is a switch:::
 105         `true`::::
 106         `yes`::::
 107         `on`::::
 108             Enable the option.
 109
 110         `false`::::
 111         `no`::::
 112         `off`::::
 113             Disable the option.
 114
 115 INI configuration file example:
 116
 117 [source,ini]
 118 ----
 119 [sessiond]
 120 daemonize=yes
 121 extra-kmod-probes=my-driver,other-module
 122 ----
 123
 124
 125 [[load]]
 126 Tracing session configuration loading
 127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 128 When the session daemon starts, it loads tracing session configurations
 129 from:
 130
 131 Without the option:--load option::
 132     In this order:
 133 +
 134 --
 135 . All the files in `$LTTNG_HOME/.lttng/sessions/auto`.
 136 +
 137 `$LTTNG_HOME` defaults to `$HOME`.
 138
 139 . All the files in +{system_sessions_auto_dir}+.
 140 --
 141 +
 142 `lttng-sessiond` only loads tracing configuration files from the
 143 directories above if its UID and their UID are the same.
 144
 145 With the option:--load='PATH' option::
 146     'PATH' is a directory:::
 147         All the files in 'PATH'.
 148
 149     'PATH' is a file:::
 150         The file 'PATH'.
 151
 152
 153 [[options]]
 154 OPTIONS
 155 -------
 156 Daemon configuration
 157 ~~~~~~~~~~~~~~~~~~~~
 158 option:-b, option:--background::
 159     Start as a Unix daemon, but keep file descriptors (console) open.
 160 +
 161 With this option, `lttng-sessiond` ensures the daemon is ready to
 162 receive client commands before it exits.
 163 +
 164 Use the option:--daemonize option instead to close the file descriptors.
 165
 166 option:-f 'PATH', option:--config='PATH'::
 167     Configure the daemon using the INI configuration file 'PATH' in
 168     addition to the default configuration files and the command-line
 169     options.
 170 +
 171 See the <<cfg,Daemon configuration>> section above.
 172
 173 option:-d, option:--daemonize::
 174     Start as a Unix daemon and close file descriptors (console).
 175 +
 176 With this option, `lttng-sessiond` ensures the daemon is ready to
 177 receive client commands before it exits.
 178 +
 179 Use the option:--background option instead to keep the file descriptors
 180 open.
 181
 182 option:-g 'GROUP', option:--group='GROUP'::
 183     Set the Unix tracing group to 'GROUP' instead of `tracing`.
 184 +
 185 This option is only meaningful when the `root` Unix user starts
 186 `lttng-sessiond`.
 187 +
 188 Members of the Unix tracing group may connect to the root session daemon
 189 and, therefore, control LTTng kernel tracing.
 190
 191 option:-l 'PATH', option:--load='PATH'::
 192     Load tracing session configurations from 'PATH', either a directory
 193     or a file, instead of loading them from the default search
 194     directories.
 195 +
 196 See the <<load,Tracing session configuration loading>> section above.
 197
 198 option:-S, option:--sig-parent::
 199     Send the `USR1` signal to the parent process to notify readiness.
 200 +
 201 You can also use the option:--daemonize or option:--background option,
 202 in which case `lttng-sessiond` ensures the daemon is ready to receive
 203 client commands before it exits.
 204
 205
 206 Linux kernel tracing
 207 ~~~~~~~~~~~~~~~~~~~~
 208 At most one of:
 209
 210 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
 211     For each 'PROBE' argument, load the LTTng kernel probe module
 212     named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the
 213     default LTTng kernel probe modules.
 214
 215 option:--kmod-probes='PROBE'[,'PROBE']...::
 216     Only load, for each 'PROBE' argument, the LTTng kernel probe
 217     module named ++lttng-probe-++__PROBE__++.ko++, instead of loading
 218     the default LTTng kernel probe modules.
 219
 220 option:--no-kernel::
 221     Disable Linux kernel tracing.
 222
 223
 224 Paths and ports
 225 ~~~~~~~~~~~~~~~
 226 option:--agent-tcp-port='PORT'::
 227     Listen on TCP port 'PORT' for agent application registration
 228     instead of a port within the range
 229     [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
 230
 231 option:-a 'PATH', option:--apps-sock='PATH'::
 232     Set the application Unix socket path to 'PATH'.
 233
 234 option:-c 'PATH', option:--client-sock='PATH'::
 235     Set the client Unix socket path to 'PATH'.
 236
 237 option:--consumerd32-libdir='PATH'::
 238     Set the 32-bit consumer daemon library directory to 'PATH'.
 239
 240 option:--consumerd32-path='PATH'::
 241     Set the 32-bit consumer daemon binary path to 'PATH'.
 242
 243 option:--consumerd64-libdir='PATH'::
 244     Set the 64-bit consumer daemon library directory to 'PATH'.
 245
 246 option:--consumerd64-path='PATH'::
 247     Set the 64-bit consumer daemon binary path to 'PATH'.
 248
 249 option:--kconsumerd-cmd-sock='PATH'::
 250     Set the command Unix socket path of the Linux kernel consumer daemon
 251     to 'PATH'.
 252
 253 option:--kconsumerd-err-sock='PATH'::
 254     Set the error Unix socket path of the Linux kernel consumer daemon
 255     to 'PATH'.
 256
 257 option:--ustconsumerd32-cmd-sock='PATH'::
 258     Set the Unix socket path of the 32-bit consumer daemon command to
 259     'PATH'.
 260
 261 option:--ustconsumerd64-cmd-sock='PATH'::
 262     Set the Unix socket path of the 64-bit consumer daemon command to
 263     'PATH'.
 264
 265 option:--ustconsumerd32-err-sock='PATH'::
 266     Set the Unix socket path of the 32-bit consumer daemon error to
 267     'PATH'.
 268
 269 option:--ustconsumerd64-err-sock='PATH'::
 270     Set the Unix socket path of the 64-bit consumer daemon error to
 271     'PATH'.
 272
 273
 274 Buffer size of event notifier error counters
 275 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 276 option:--event-notifier-error-buffer-size-kernel='SLOTS'::
 277     Set the size of the kernel event notifier error counter buffers to
 278     'SLOTS'{nbsp}slots.
 279
 280 option:--event-notifier-error-buffer-size-userspace='SLOTS'::
 281     Set the size of the user space event notifier error counter buffers
 282     to 'SLOTS'{nbsp}slots.
 283
 284 As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
 285 may change in the future.
 286
 287
 288 Verbosity
 289 ~~~~~~~~~
 290 option:-q, option:--quiet::
 291     Suppress all messages, including warnings and errors.
 292 +
 293 You may :not: use this option with the option:--verbose and
 294 option:--verbose-consumer options.
 295
 296 option:-v, option:--verbose::
 297     Increase verbosity.
 298 +
 299 Specify this option up to three times to get more levels of verbosity.
 300 +
 301 You may :not: use this option with the option:--quiet option.
 302
 303 option:--verbose-consumer::
 304     Increase the verbosity of the consumer daemons which this session
 305     daemon spawns.
 306 +
 307 You may :not: use this option with the option:--quiet option.
 308
 309
 310 Program information
 311 ~~~~~~~~~~~~~~~~~~~
 312 include::common-help-option.txt[]
 313
 314 option:-V, option:--version::
 315     Show version and quit.
 316
 317
 318 ENVIRONMENT VARIABLES
 319 ---------------------
 320 `LTTNG_ABORT_ON_ERROR`::
 321     Set to `1` to abort the process after the first error is
 322     encountered.
 323
 324 `LTTNG_APP_SOCKET_TIMEOUT`::
 325     Timeout (in seconds) of the application socket when
 326     sending/receiving commands.
 327 +
 328 After this period of time, `lttng-sessiond` unregisters the application.
 329 +
 330 Set to `0` or `-1` to set an infinite timeout.
 331 +
 332 Default: +{default_app_socket_rw_timeout}+.
 333
 334 `LTTNG_CONSUMERD32_BIN`::
 335     32-bit consumer daemon binary path.
 336 +
 337 The option:--consumerd32-path option overrides this variable.
 338
 339 `LTTNG_CONSUMERD32_LIBDIR`::
 340     32-bit consumer daemon library directory path.
 341 +
 342 The option:--consumerd32-libdir option overrides this variable.
 343
 344 `LTTNG_CONSUMERD64_BIN`::
 345     64-bit consumer daemon binary path.
 346 +
 347 The option:--consumerd64-path option overrides this variable.
 348
 349 `LTTNG_CONSUMERD64_LIBDIR`::
 350     64-bit consumer daemon library directory path.
 351 +
 352 The option:--consumerd64-libdir option overrides this variable.
 353
 354 `LTTNG_DEBUG_NOCLONE`::
 355     Set to `1` to disable the use of man:clone(2)/man:fork(2).
 356 +
 357 Setting this variable is considered insecure, but it's required to allow
 358 debuggers to work with `lttng-sessiond` on some operating systems.
 359
 360 `LTTNG_EXTRA_KMOD_PROBES`::
 361     Extra LTTng kernel probe modules to load.
 362 +
 363 See the option:--extra-kmod-probes option which overrides this
 364 environment variable.
 365
 366 `LTTNG_KMOD_PROBES`::
 367     Exclusive LTTng kernel probe modules to load.
 368 +
 369 See the option:--kmod-probes option which overrides this environment
 370 variable.
 371
 372 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 373     Socket connection, receive, and send timeout (milliseconds).
 374 +
 375 Set to `0` or `-1` to use the timeout of the operating system (default).
 376
 377 `LTTNG_SESSION_CONFIG_XSD_PATH`::
 378     Tracing session configuration XML schema definition (XSD) path.
 379
 380
 381 FILES
 382 -----
 383 `$LTTNG_HOME/.lttng`::
 384     Unix user's LTTng runtime and configuration directory.
 385
 386 `$LTTNG_HOME/lttng-traces`::
 387     Default output directory of LTTng traces in local and snapshot
 388     modes.
 389 +
 390 Override this path with the nloption:--output option of the
 391 man:lttng-create(1) command.
 392
 393 `$LTTNG_HOME/.lttng/sessions/auto`::
 394     Directory from which `lttng-sessiond` loads Unix user tracing
 395     session configurations when starting.
 396 +
 397 See the <<load,Tracing session configuration loading>> section above to
 398 learn more.
 399
 400 +{system_sessions_auto_dir}+::
 401     Directory from which `lttng-sessiond` loads system-wide tracing
 402     session configurations when starting.
 403 +
 404 See the <<load,Tracing session configuration loading>> section above to
 405 learn more.
 406
 407 `$LTTNG_HOME/.lttng/lttng.conf`::
 408     Unix user's LTTng daemon INI configuration file.
 409 +
 410 See the <<cfg,Daemon configuration>> section above to learn more.
 411
 412 +{system_lttng_conf}+::
 413     System-wide LTTng daemon INI configuration file.
 414 +
 415 See the <<cfg,Daemon configuration>> section above to learn more.
 416
 417 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
 418
 419
 420 EXIT STATUS
 421 -----------
 422 *0*::
 423     Success
 424
 425 *1*::
 426     Error
 427
 428 *3*::
 429     Fatal error
 430
 431
 432 LIMITATIONS
 433 -----------
 434 For an unprivileged Unix user running `lttng-sessiond`, the maximum
 435 number of file descriptors per process is usually 1024. This limits the
 436 number of traceable applications, since, for each instrumented
 437 application, there are two file descriptors per CPU as well as one
 438 socket for bidirectional communication.
 439
 440 For the `root` user, the limit is usually 65,535.
 441
 442
 443 include::common-footer.txt[]
 444
 445
 446 SEE ALSO
 447 --------
 448 man:lttng(1)