X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-sessiond.8.txt;h=2bfce1c3744571fad962b1e9a083d75478509b0a;hb=e971184584781f70bbbfc52bbede8b9abf0436e5;hp=8edb004b7d95c83f104d54347560671b0bff0e57;hpb=484b2a0cbefcf0c7072622a5a411ea5ed849da28;p=lttng-tools.git diff --git a/doc/man/lttng-sessiond.8.txt b/doc/man/lttng-sessiond.8.txt index 8edb004b7..2bfce1c37 100644 --- a/doc/man/lttng-sessiond.8.txt +++ b/doc/man/lttng-sessiond.8.txt @@ -1,6 +1,8 @@ lttng-sessiond(8) ================= -:revdate: 21 April 2021 +:revdate: 14 June 2021 +:daemon-bin-name: lttng-sessiond +:daemon-ini-section: sessiond NAME @@ -36,8 +38,8 @@ include::common-intro.txt[] An LTTng session daemon, `lttng-sessiond`, is a program which: -* Manages tracing sessions (see man:lttng-create(1) to learn more about - tracing sessions). +* Manages recording sessions (see man:lttng-concepts(7) to learn more + about recording sessions). * Controls the various components (like tracers and consumer daemons) of LTTng. @@ -71,46 +73,19 @@ commands before it exits. NOTE: The LTTng project recommends that you start the session daemon at boot time for stable and long-term tracing. +[NOTE] +==== +For an unprivileged Unix user running `lttng-sessiond`, the maximum +number of file descriptors per process is usually 1024. This limits the +number of traceable applications, since, for each instrumented +application, there are two file descriptors per CPU as well as one +socket for bidirectional communication. -[[cfg]] -Daemon configuration -~~~~~~~~~~~~~~~~~~~~ -When you run `lttng-sessiond`, it configures itself from, in this order: - -. The INI configuration file +{system_lttng_conf}+, if any. - -. The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any. -+ -`$LTTNG_HOME` defaults to `$HOME`. - -. With the option:--config='PATH' option: the INI configuration file - 'PATH'. - -. The command-line options. - -Each step can override a previous configuration property. - -In INI configuration files, the session daemon only reads the properties -under the `sessiond` INI section. Each INI property is: - -Key:: - The long name of a command-line option to set (see the - <> section below). - -Value:: - The selected command-line option accepts an argument::: - Option argument (string). +For the `root` user, the limit is usually 65,535. +==== - The selected command-line option is a switch::: - `true`:::: - `yes`:::: - `on`:::: - Enable the option. - `false`:::: - `no`:::: - `off`:::: - Disable the option. +include::common-daemon-cfg.txt[] INI configuration file example: @@ -123,10 +98,10 @@ extra-kmod-probes=my-driver,other-module [[load]] -Tracing session configuration loading -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When the session daemon starts, it loads tracing session configurations -from: +Recording session configuration loading +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +When the session daemon starts, it loads recording session +configurations from: Without the option:--load option:: In this order: @@ -139,8 +114,8 @@ Without the option:--load option:: . All the files in +{system_sessions_auto_dir}+. -- + -`lttng-sessiond` only loads tracing configuration files from the -directories above if its UID and their UID are the same. +`lttng-sessiond` only loads recording session configuration files from +the directories above if its UID and their UID are the same. With the option:--load='PATH' option:: 'PATH' is a directory::: @@ -153,8 +128,8 @@ With the option:--load='PATH' option:: [[options]] OPTIONS ------- -Daemon configuration -~~~~~~~~~~~~~~~~~~~~ +General daemon configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ option:-b, option:--background:: Start as a Unix daemon, but keep file descriptors (console) open. + @@ -168,7 +143,7 @@ option:-f 'PATH', option:--config='PATH':: addition to the default configuration files and the command-line options. + -See the <> section above. +See the ``<>'' section above. option:-d, option:--daemonize:: Start as a Unix daemon and close file descriptors (console). @@ -189,11 +164,12 @@ Members of the Unix tracing group may connect to the root session daemon and, therefore, control LTTng kernel tracing. option:-l 'PATH', option:--load='PATH':: - Load tracing session configurations from 'PATH', either a directory - or a file, instead of loading them from the default search + Load recording session configurations from 'PATH', either a + directory or a file, instead of loading them from the default search directories. + -See the <> section above. +See the ``<>'' section +above. option:-S, option:--sig-parent:: Send the `USR1` signal to the parent process to notify readiness. @@ -211,11 +187,15 @@ option:--extra-kmod-probes='PROBE'[,'PROBE']...:: For each 'PROBE' argument, load the LTTng kernel probe module named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the default LTTng kernel probe modules. ++ +See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable. option:--kmod-probes='PROBE'[,'PROBE']...:: Only load, for each 'PROBE' argument, the LTTng kernel probe module named ++lttng-probe-++__PROBE__++.ko++, instead of loading the default LTTng kernel probe modules. ++ +See also the `LTTNG_KMOD_PROBES` environment variable. option:--no-kernel:: Disable Linux kernel tracing. @@ -236,15 +216,23 @@ option:-c 'PATH', option:--client-sock='PATH':: option:--consumerd32-libdir='PATH':: Set the 32-bit consumer daemon library directory to 'PATH'. ++ +See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable. option:--consumerd32-path='PATH':: Set the 32-bit consumer daemon binary path to 'PATH'. ++ +See also the `LTTNG_CONSUMERD32_BIN` environment variable. option:--consumerd64-libdir='PATH':: Set the 64-bit consumer daemon library directory to 'PATH'. ++ +See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable. option:--consumerd64-path='PATH':: Set the 64-bit consumer daemon binary path to 'PATH'. ++ +See also the `LTTNG_CONSUMERD32_BIN` environment variable. option:--kconsumerd-cmd-sock='PATH':: Set the command Unix socket path of the Linux kernel consumer daemon @@ -315,8 +303,20 @@ option:-V, option:--version:: Show version and quit. -ENVIRONMENT VARIABLES ---------------------- +EXIT STATUS +----------- +*0*:: + Success + +*1*:: + Error + +*3*:: + Fatal error + + +ENVIRONMENT +----------- `LTTNG_ABORT_ON_ERROR`:: Set to `1` to abort the process after the first error is encountered. @@ -334,28 +334,33 @@ Default: +{default_app_socket_rw_timeout}+. `LTTNG_CONSUMERD32_BIN`:: 32-bit consumer daemon binary path. + -The option:--consumerd32-path option overrides this variable. +The option:--consumerd32-path option overrides this environment +variable. `LTTNG_CONSUMERD32_LIBDIR`:: 32-bit consumer daemon library directory path. + -The option:--consumerd32-libdir option overrides this variable. +The option:--consumerd32-libdir option overrides this environment +variable. `LTTNG_CONSUMERD64_BIN`:: 64-bit consumer daemon binary path. + -The option:--consumerd64-path option overrides this variable. +The option:--consumerd64-path option overrides this environment +variable. `LTTNG_CONSUMERD64_LIBDIR`:: 64-bit consumer daemon library directory path. + -The option:--consumerd64-libdir option overrides this variable. +The option:--consumerd64-libdir option overrides this environment +variable. `LTTNG_DEBUG_NOCLONE`:: Set to `1` to disable the use of man:clone(2)/man:fork(2). + -Setting this variable is considered insecure, but it's required to allow -debuggers to work with `lttng-sessiond` on some operating systems. +Setting this environment variable is considered insecure, but it's +required to allow debuggers to work with `lttng-sessiond` on some +operating systems. `LTTNG_EXTRA_KMOD_PROBES`:: Extra LTTng kernel probe modules to load. @@ -375,7 +380,7 @@ variable. Set to `0` or `-1` to use the timeout of the operating system (default). `LTTNG_SESSION_CONFIG_XSD_PATH`:: - Tracing session configuration XML schema definition (XSD) path. + Recording session configuration XML schema definition (XSD) path. FILES @@ -391,58 +396,36 @@ Override this path with the nloption:--output option of the man:lttng-create(1) command. `$LTTNG_HOME/.lttng/sessions/auto`:: - Directory from which `lttng-sessiond` loads Unix user tracing + Directory from which `lttng-sessiond` loads Unix user recording session configurations when starting. + -See the <> section above to -learn more. +See the ``<>'' section +above to learn more. +{system_sessions_auto_dir}+:: - Directory from which `lttng-sessiond` loads system-wide tracing + Directory from which `lttng-sessiond` loads system-wide recording session configurations when starting. + -See the <> section above to -learn more. +See the ``<>'' section +above to learn more. `$LTTNG_HOME/.lttng/lttng.conf`:: Unix user's LTTng daemon INI configuration file. + -See the <> section above to learn more. +See the ``<>'' section above to learn more. +{system_lttng_conf}+:: System-wide LTTng daemon INI configuration file. + -See the <> section above to learn more. +See the ``<>'' section above to learn more. NOTE: `$LTTNG_HOME` defaults to `$HOME`. -EXIT STATUS ------------ -*0*:: - Success - -*1*:: - Error - -*3*:: - Fatal error - - -LIMITATIONS ------------ -For an unprivileged Unix user running `lttng-sessiond`, the maximum -number of file descriptors per process is usually 1024. This limits the -number of traceable applications, since, for each instrumented -application, there are two file descriptors per CPU as well as one -socket for bidirectional communication. - -For the `root` user, the limit is usually 65,535. - - include::common-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-concepts(7)