Logging

Posit Workbench provides the ability to change various facets of its logging functionality, such as changing the logger type (e.g. syslog vs. file) on a per-executable or per-section basis. In most configurations, it is recommended that you do not change the logging configuration, but in some circumstances it is desirable to turn on debug logging to help troubleshoot issues.

Default log file locations

Workbench programs that run on behalf of the rstudio-server user, such as rserver, and rserver-launcher create log files using the executable name in the directory:

    /var/log/rstudio/rstudio-server

When using the Job Launcher, the log files for the Launcher and its plugins are stored under the directory:

    /var/log/rstudio/launcher

Logs for the rsession and the rworkspaces programs, run on behalf of each session user, are stored by default in the home directory of that user in:

    ~/.local/share/rstudio/log

This path is configured with XDG_DATA_HOME.

Configuration file

The logging configuration file is located at /etc/rstudio/logging.conf. It allows you to specify logging options in a hierarchy of three different types:

  1. Global ([*])
  2. Per executable ([@executable-name])
  3. Per log section ([log-section-name])

Debug logging

To help diagnose problems, enable debug logging for all executables and sections create /etc/rstudio/logging.conf with:

[*]
log-level=debug
Important

Once you’ve fixed the problem, remove the log-level=debug setting to improve efficiency.

Reloading logging configuration

After makes changes to the logging configuration, either reload the configuration values, or restart Workbench to apply the change.

Configuration example

Here’s a more complete example logging.conf file:

/etc/rstudio/logging.conf
[*]
log-level=info
logger-type=syslog

[@rserver]
log-level=debug
logger-type=file
max-size-mb=10
rotate-days=2
max-rotations=50
delete-days=10
warn-syslog=0

[file-locking]
log-dir=/var/log/file-locking
log-file-mode=600

This example specifies that by default, all logging should be sent to syslog at info level or higher. Debug logging is enabled for the rserver executable specifically, where logs are written to file with a maximum log file size of 10MB, in the default /var/log/rstudio/rstudio-server directory, with a maximum of 50 log file rotations to be retained for up to 10 days before they are deleted. File locking logging is also specifically redirected to a different logging directory, /var/log/file-locking, with a specific file creation mode of 600. All logging sections named file-locking which occur in the rserver process will be logged to file, whereas the same logging sections in other binaries will continue to be logged to syslog.

The following settings may be specified in /etc/rstudio/logging.conf:

Config Option Description Default Value
log-level The minimum log level to capture. Can be one of debug, info, warn, or error. warn
logger-type The type of logger to use. Can be one of stderr, syslog, or file. file
log-message-format The format of log messages. Can be one of pretty or json. pretty

When using the file logger, the following can also be specified:

Config Option Description Default Value
log-dir The log directory to store log files in. The resulting log file name is based on the executable name (and optionally the process ID). /var/log/rstudio/rstudio-server
log-file-mode The filemode to use when creating the log file. Must be a valid POSIX octal file mode. 666 (All read/write)
log-file-include-pid Whether to include the process id in the filename. Useful for differentiating between multiple processes of the same name. Can be 0 (false) or 1 (true) 0 (false)
rotate Whether or not to rotate the log file as it reaches maximum size. Can be 0 (false) or 1 (true) 1 (true)
max-size-mb Maximum allowable size of the file before it is rotated. Only applicable if rotate is enabled. 2 (MB)
rotate-days Number of days before a log file is rotated. Set to 0 to disable rotation by time. Only applicable if rotate is enabled. 1
max-rotations Number of maximum log rotation files that can be created. Set to 0 to allow an unbounded amount of rotated log files. 100
delete-days Number of days before a rotated log file is deleted. Set to 0 to disable deletion of old log files. Only applicable if rotate is enabled. 30
warn-syslog Whether or not to also send warn/error logs to syslog in addition to file for better admin visibility. 1 (true)

Note that if it does not exist, the specified log-dir will be created automatically with 775 permissions. If you want to use stricter permissions, you should ensure that the directory is created with the desired permissions before starting any Workbench services.

It is expected that any log files not owned by the root user will still be modifiable by root. You must ensure that the log directory that you specified is not a root squash mount, otherwise logs will not be writeable during initialization of Workbench processes.

List of logging sections

The following is a list of logging sections that may be used within the logging configuration file.

Section Name Description
file-locking Logging of file locking operations, such as processes acquiring and releasing locks.

List of executables

The following three categories of executables use the logging system and can be targeted with [@executable-name].

Posit Workbench executables

These executables are run using the configured rstudio-server user and store logs in /var/log/rstudio/rstudio-server by default.

Executable Name Description
rserver The main Workbench server process for the rstudio-server service.
rserver-launcher Launches individual user sessions.
rsandbox Start the PAM session before exec’ing the session executable.
rserver-acls Used for project sharing to adjust acls of files for managing secure access.
rserver-pam The default executable for auth-pam-helper-path, used for validating PAM logins by rserver.
rserver-openid Used with auth-openid=1 to proxy auth requests.
rserver-saml Used with auth-saml=1 to proxy auth requests.
rserver-admin Manages the admin page.
rserver-http An automatically configured and managed nginx server that proxies requests to rserver.
rserver-session-reaper Cleans up expired local sessions.
Launcher executables

When Posit Workbench is configured to use Launcher sessions, it starts the rstudio-launcher service. That service provides these executables that use the log directory: /var/log/rstudio/launcher by default.

Executable Name Description
rstudio-launcher Job Launcher main process
rstudio-local-launcher Job Launcher Local plugin
rstudio-kubernetes-launcher Job Launcher Kubernetes plugin
rstudio-slurm-launcher Job Launcher Slurm plugin
Session executables

These executables are run as the session user and store their results in ~/.local/share/rstudio/log/ by default. The log file name includes the session user’s username - e.g. ‘rsession-username.log’. You can either target all rsessions with [@rsession] or target a specific user with [@rsession-username].

Executable Name Description
rsession The main session process for R applications run in the RStudio Pro and RStudio Open Source IDE.
rworkspaces The process started for each session user in Posit Workbench for managing session metadata for the homepage.

Posit Workbench monitor logging

The Posit Workbench Monitor collects errors and warnings from multiple executables as an alternative to logger-type=syslog for centralized log file management. By default, it logs to the file:

    /var/lib/rstudio-server/monitor/log/rstudio-server.log

Errors and warnings are collected from: rserver, rserver-admin, rsession, rstudio-launcher, and rworkspaces.

For more information about how to configure monitor logging, see Monitoring Configuration.

Environment variable configuration

Logging can also be controlled using environment variables. The environment variables allow you to override logger settings specified in a logging.conf file. The environment variables always take precedence.

You can set the following environment variables to configure various facets of the logger. Note that the environment variable values will apply to all logging sections.

Environment Variable Description
RS_LOG_LEVEL The desired level to log at. See log-level above for supported values.
RS_LOGGER_TYPE The type of logger to use. See logger-type above for supported values.
RS_LOG_MESSAGE_FORMAT The log message format to use. See log-message-format above for supported values.
RS_LOG_DIR The directory where logs should be written if using the file logger.
RS_LOG_CONF_FILE Specifies a specific logging.conf file to use for configuring logging. If any other logging environment variables are set, they will take precedence over any of the logging.conf settings.