Session Management
This page covers the basics on using the Posit Workbench home page to work in a multi-session environment.
Accessing the home page
After logging in, Workbench will redirect users to the Workbench home page. It consists of three sections:
- Sessions: manage sessions and create new ones.
- Projects: create sessions for recently used/shared projects.
- Recently Published: create sessions for recently published projects.
To help you keep track of your running sessions, Posit Workbench comes with a home page that allows users to:
- View the status of all running sessions: pending, idle, active, shut down, or suspended.
- 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.
Session states
Sessions are long-running tasks that continue to be available until you explicitly quit them. This means that you can kick off a long-running job in one session and switch to another to continue working.
Sessions may be in one of the following states:
- Active: The session is running, and there has been recent user interaction or processing.
- Idle: The session is running, and there has been no recent user interaction or processing.
- Suspended: The session is not currently running as it has been suspended. Session information has been saved for future restoration. The session is restored when clicked on 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, and any unsaved work will be lost. This is done through quitting or force quitting the session.
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 is restored with all active work preserved, and you can resume work from where you had last left off. To change the session idle configuration, refer your server administrator to the Session Timeout section of the Admin Guide.
As a general rule, the larger the objects are, the longer it will take 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 will be 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 the + New Session button.
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.
Depending on how your server administrator has configured your Workbench deployment, you will see different settings under the OPTIONS section of the New Session modal. For example, Workbench can also be configured to launch jobs into IT-managed computing resources in Kubernetes or Slurm clusters, which may give additional options during new session creation such as CPUs and Memory.
Opening existing sessions and sessions from projects
You can open existing sessions by clicking the session name.
You can open an existing or shared project in a new session by clicking:
- on a project under the Projects pane or
- a recently published project under the Recently Published pane.
This causes a prompt to display to create a session with that project already loaded for you using your preferred editor.
When opening a project under the Projects and Recently Published columns on the right side, Workbench attempts to match with the appropriate editor based on the project type. R Projects will be prompted with the RStudio IDE as the preferred editor and Jupyter Notebooks will be prompted with the choice between JupyterLab and JupyterNotebook. At this time, projects will not be matched with the VS Code editor.
Ending sessions
Closing a browser window does not end a session, therefore, it is a good practice to routinely go through and clean up the sessions you aren’t using. This gives the compute resources back to the server to be available for other users.
To quit a session:
- To the right of the session that you wish to force quit, click the Quit button.
- Click the Quit Session button.
You can quit all open sessions with the Quit All button located at the top right of the Sessions section. Any unsaved work will be lost, so be sure to save work to your version control system of choice, or locally, before quitting.
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:
- Click the Quit button located to the right of the session you wish to force quit.
- Select the optional check box to enable Force Quit (kills all child processes).
- Click the Quit Session button.
This will forcefully stop your process and all of its descendant processes. Force quitting does not 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 started sessions
To find a started session’s diagnostics:
- Navigate to the Workbench home page.
- Locate the session that you wish to view diagnostics for and click Info.
- From the RStudio Pro Session window, click the Launcher Diagnostics tab.
- Under the Running status icon, click Details.
Below is an example of a session’s diagnostics:
