| 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) |