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:

Global ([*])
Per executable ([@executable-name])
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 making 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.