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