Session Management
This page covers the basics of using the Posit Workbench home page to work in a multi-session environment.
The home page
After logging in, the Workbench home page that consists of three sections (panes) for session management displays:
- Sessions pane: manage sessions and create new ones.
- Projects pane: create sessions for recently used/shared projects.
- Recently Published pane: create sessions for recently published projects.
To help track your running sessions, the home page allows users to:
- View the session state of all running sessions:
- active, idle, suspended, pending, or shut down
- Gracefully or forcefully exit a running session.
- View recently accessed projects.
- View recently published projects.
- Participate in one or more shared projects.
- Run multiple analyses in parallel.
What are sessions?
Unlike many web applications, Workbench sessions continue to run on the server even after you close your browser window.
This means that you can kick off a long-running job in one session and switch to another to continue working.
Session states
Sessions may be in one of the following states:
Active:
- The session is running with recent user interaction or processing.
Idle:
- The session is running with no recent user interaction or processing.
Suspended: Only applicable to RStudio Pro sessions1
- The session is not currently running as it has been suspended.
- Session information is saved for future restoration.
- The session is restored when selected from the home page with all active work preserved.
Pending:
- The session is in the process of being made available to the user.
Shutting Down:
- The session has been exited.
- Any unsaved work is lost.
- This is done through quitting or force quitting the session.
Session state behavior explained
When sessions have been idle (no processing or user interaction) for a specified period (2 hours by default), they are suspended to free up server resources.
When you next interact with that session, it restores with all active work preserved, and you can resume work from where you had last left off. To change the session idle configuration, update the session-timeout-minutes option. Refer your server administrator to the Session Timeout section of the Administrator Guide.
As a general rule, the larger the objects, the longer it takes to resume a session that was suspended.
Only objects that have been allocated within R’s memory are written to disk and may be restored later. Generally, this means that any object that could be saved as a .rds file is safely suspended and restored later. Any R objects that cannot be saved to .rds, such as objects requiring deserialization or relying on external pointers, may experience unexpected behavior when suspending and could be inaccessible upon restoration.
Currently, only sessions using RStudio Pro have the capability to be suspended and later restored.
Managing sessions
Starting new sessions
To start a new session, from the Sessions section click + New Session.
When creating a new session, you may choose from the different editor options that have been configured by your administrator, including RStudio Pro, VS Code, JupyterLab, and Jupyter Notebook.
Different settings display in the Cluster Options settings of the New Session dialog based on your Workbench deployment’s unique configuration (managed by your server administrator).
For example, Workbench can be configured to launch jobs into IT-managed computing resources in Kubernetes or Slurm clusters, which can display additional configuration options during new session creation (such as CPUs and Memory).
Opening existing sessions and sessions from projects
Open an existing session by clicking the session name.
You can open an existing or shared project in a new session from the Projects page by clicking either:
- A project listed in the Projects section.
- A recently published project listed in the Recently Published section.
A New Project Session dialog displays to create a session. The project is already loaded for you using your preferred editor.
When opening a project listed in the Projects and Recently Published columns (within the Projects pane), Workbench attempts to match with the appropriate editor based on the project type. R Projects prompt with the RStudio IDE as the preferred editor and Jupyter notebooks prompt with the choice between JupyterLab or Jupyter Notebook. Currently, projects are not matched with the VS Code editor regardless of the project type.
Quitting sessions
Closing a browser window does not quit a session. Therefore, it is a good practice to routinely go through and clean up the sessions you aren’t using. This frees compute resources back to the server to be available for other users.
When quitting a session, all unsaved work is lost. Be sure to save work to your version control system of choice, or locally, before quitting.
To quit a single session:
To the right of the session that you wish to force quit, click the Quit button.
Click the Quit Session button.
Quitting sessions in Workbench
To end (quit) all open sessions:
At the top right of the Sessions section, click Quit All.
Quit all sessions
In some rare cases, it might be necessary to force quit sessions. Typically, this is done when a session is not responding to inputs and may be part of a larger troubleshooting effort.
To forcefully quit your session:
Located to the right of the session you wish to force quit, click the Info button
In the Session section, scroll down until the Force Quit button displays.
Click the Force Quit.
Forcefully quitting sessions in Workbench
This forcefully stops your process and all of its descendant processes. Force quitting doesn’t allow them to attempt to gracefully quit on their own. Consider using this option only as a last resort.
Automatic cleanup of forgotten, long-running jobs is an optional setting, disabled by default, that may be configured by your server administrator. It is used to automatically reclaim temporary disk space used by a long-running session without user input regardless of computation status and to stop its processes and children.
If you are encountering unexpected session behavior that you suspect is due to this setting, refer your Workbench administrator to the Session Timeout Kill section of the Admin Guide.
Troubleshooting
Find session diagnostics for active sessions
To find the diagnostics for an active session:
Navigate to the Workbench home page.
Locate the session that you wish to view diagnostics for and click Info.
Getting session’s info From the RStudio Pro Session window, select the Launcher Diagnostics tab.
Getting session’s launcher diagnostics Under the Running status icon, click Details.
Getting session’s details
Below is an example of a session’s diagnostics:
Footnotes
Currently, only sessions using RStudio Pro have the capability to be suspended and later restored. Other session types won’t switch to the Suspended state and there is no Suspend control option.↩︎