R Executable and Libraries
Locating R
RStudio Pro uses the version of R pointed to by the output of the following command:
$ which RThe which command performs a search for the R executable using the system PATH. RStudio Pro will therefore by default bind to the same version that is run when R is executed from a terminal.
For versions of R installed by system package managers this will be /usr/bin/R. For versions of R installed from source this will typically (but not always) be /usr/local/bin/R.
If you want to override which version of R is used then you can use the rsession-which-r setting. For example:
/etc/rstudio/rserver.conf
rsession-which-r=/usr/local/bin/RNote that this change will not take effect until the server is restarted.
Using multiple versions of R
The section above describes how RStudio Pro locates the global default version of R. It’s also possible to specify alternate versions of R either by user or by group. The R versions section describes this in more detail.
Customizing session launches
Profile script execution
RStudio Pro launches RStudio Pro Sessions under a bash login shell. This means that prior to the execution of the RStudio Pro Session the bash shell will read and execute commands from this file if it exists:
/etc/profileAfter reading that file, it looks for the following files and reads and executes commands from the first one that exists and is readable (it’s important to note that only one of these files will be read and executed):
~/.bash_profile
~/.bash_login
~/.profileIf you have further RStudio-Pro-specific initialization logic (exporting environment variables, etc.) you can optionally create an RStudio Pro Session specific profile script at:
/etc/rstudio/rsession-profileIf it exists this script will be executed prior to the bash shell that launches the RStudio Pro Session. This script must be executable by all Post Workbench users, so it is recommended that you set its file permissions to 755 via the following command:
chmod 755 /etc/rstudio/rsession-profileIn some situations, you will not want to run user shell profile scripts. This is also a good way to troubleshoot the inability for sessions to launch, as it could indicate a conflict is occurring due to environment variables being set in the shell profiles. To disable execution of the shell profiles, set the rsession-no-profile option to 1 in /etc/rstudio/rserver.conf. For example:
/etc/rstudio/rserver.conf
rsession-no-profile=1Environment variables
RStudio Pro Sessions inherit environment variables that are explicitly exported from the profile scripts described above. It’s also possible to append paths to the LD_LIBRARY_PATH environment variable using the rsession-ld-library-path option (see previous section for details).
Another source of environment variables are PAM sessions. On Debian/Ubuntu systems, the default PAM profile run by Posit Workbench includes the environment variables defined in /etc/security/pam_env.conf and /etc/environment. To learn more about setting environment variables with PAM you should consult the PAM Sessions section as well as the documentation on the pam_env module here: http://linux.die.net/man/8/pam_env.
Program supervisors
You may also wish to run RStudio Pro Sessions under a program supervisor that modifies their environment or available resources. You can specify a supervisor (and the arguments which control it’s behavior) using the rsession-exec-command setting. For example:
/etc/rstudio/rserver.conf
rsession-exec-command=nice -n 10This example uses the nice command to run all RStudio Pro Sessions with a lower scheduling priority. See http://linux.die.net/man/1/nice for more details on nice. Note that for nice in particular it’s possible to accomplish the same thing using user and group profiles (and even specify a custom priority level per user or group). See the User and Group Profiles section for more details.
Diagnosing session problems
Posit Workbench allows you to launch sessions in a diagnostics mode to capture extended session trace information in the event that you run into problems. This mode captures the environment variables that are set by all of the profile scripts, loading of any modules, arguments passed to the session, and the exit code of the session and any stack trace information if the session crashes.
We recommend that you send these files to Posit support to aid in troubleshooting any session launch issues should they arise.
Either enable diagnostics for an individual user session, or system-wide for all sessions.
Enabling session diagnostics for individual sessions
To enable diagnostics for an individual user’s sessions, create a text file in the user’s home directory: ~/.config/rstudio/rsession-diagnostics that contains the type of diagnostics desired: debug (for debug logging only), or strace for debug logging and a system call strace. For example, run these commands to enable strace logging for the current user:
mkdir -p ~/.config/rstudio
echo "strace" > ~/.config/rstudio/rsession-diagnosticsWhen the next RStudio Pro session is started, logs are created in the user’s rstudio log directory, by default: ~/.local/share/rstudio/log. The file: rsession-diagnostics.log contains startup info including environment variables. The file rsession-username.log has debug log messages.
When using strace mode, an additional file is created called rsession-diagnostics.log.strace that contains the output of the linux strace command for the session.
To disable diagnostic collection, either remove the file ~/.config/rstudio/rsession-diagnostics or change its contents to the word off.
Session Protocol Debug
Debug logging may also be enabled for an RStudio Pro session by enabling the Session Protocol Debug option in the Tools -> Show Command Palette option menu in RStudio. Enabling this option adds detail to the standard debug logs including trace messages for operations relayed between browser and rsession. Enabling this option will automatically enable debug logging, but after the session has started. Use rsession-diagnostics to capture the complete debug log for the session, including startup messages.
Enabling session diagnostics system wide
To enable collection of diagnostic data for all RStudio Pro sessions, set the rsession-diagnostics-enabled flag in /etc/rstudio/rserver.conf like below:
/etc/rstudio/rserver.conf
rsession-diagnostics-enabled=1When this setting is enabled, all sessions that are started will create a diagnostics file that contains extended launch diagnostics under the /tmp directory by default. To change the location, use the rsession-diagnostics-dir to point to the desired directory, like so:
/etc/rstudio/rserver.conf
rsession-diagnostics-dir=/tmp/diagnosticsBe aware that this directory should be accessible by all users of the system. If it does not exist, Posit Workbench will attempt to create it and set its permissions to Read/Write/Execute for everyone (file permissions of 777).
Remember to turn the option off when you are done to prevent diagnostic information from accumulating in this directory.
To diagnose containerized sessions (e.g. Kubernetes) launched via the Job Launcher, set rsession-diagnostics-dir to a shared folder mounted in the container via /etc/rstudio/launcher-mounts. Otherwise sessions may fail to launch due to the default location under /tmp not being available in the containers.
When running Slurm sessions with Singularity, it should be noted that the rsession-diagnostics-dir must still have accessible permissions so that the Slurm sessions can write to it.
For other types of remote sessions, such as running non-containerized sessions, configuring launcher-mounts is not necessary. For load-balanced configurations, we recommend that each load-balanced node running Workbench should be configured independently with rsession-diagnostics-dir when needed.
Strace information can be included in the diagnostics file by adding the rsession-diagnostics-strace-enabled flag as shown below. Before using this setting, ensure that strace is installed and is available on your users’ path. These files will grow very large in a short amount of time so remember to turn off this option and do not use it to capture extended session runs.
/etc/rstudio/rserver.conf
rsession-diagnostics-enabled=1
rsession-diagnostics-strace-enabled=1Safe mode
Two of the most common session startup problems are (1) oversized global R environments, which take a long time to load into memory when the session is resumed, and (2) problematic code in .Rprofile which takes too long to run or throws errors during startup.
In order to help eliminate these variables as the cause of session startup issues, Posit Workbench can start sessions in Safe Mode. This mode starts the session without running .Rprofile or restoring the global environment. If a session takes too long to start, the user will be given the option to restart a session in Safe Mode.
It is also possible to control these features independently, which can be helpful when troubleshooting issues.
Skipping workspace restoration
To skip workspace restoration (i.e., reloading the contents of the global environment), append ?restore_workspace=0 to the RStudio Pro Session’s full URL. For example:
https://yourcorp/rstudio/s/4cc57da229b59e81c306b/?restore_workspace=0Note that this will work only if the session is not already running. If you are currently waiting for the session to start, it is too late to try to skip workspace restoration, since it is already in progress. Kill or force-kill the session before restarting the attempt with the restore_workspace flag.
Omitting .Rprofile
To skip executing .Rprofile, append run_rprofile=0 to the RStudio Pro Session’s full URL. For example:
https://yourcorp/rstudio/s/4cc57da229b59e81c306b/?run_rprofile=0Just like restore_workspace, this can only be used prior to the session starting.
Note that Safe Mode is only available when Posit Workbench itself is starting sessions, so it is not a useful troubleshooting technique when sessions are being run using the Job Launcher.