Logging

RStudio provides the ability to change various facets of its logging functionality, such as changing the logger type (syslog vs file) on a per-binary 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.

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-binary ([@binary name])
  3. Per log section ([log section name])

For example:

# /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 configuration specifies that by default, all logging should be sent to syslog at info level or higher. Debug logging is enabled for the rserver binary 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 binary 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 RStudio 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 RStudio 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.

Reloading Configuration

In order to reload the logging settings during run-time of a process, simply send the SIGHUP signal to the desired process, and the logging configuration will be reloaded for that binary.

For example, to send the SIGHUP signal to the rserver process after changing the configuration file:

pidof rserver | sudo xargs kill -s SIGHUP

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.