Description

When investigating Workspace behavior, it would be valuable to track why a workspace was started. Currently, currently there's no clear way to determine if a workspace was started due to a user SSH connection, VS Code connection, or direct console action.

Proposed Solution

Add a build_reason field to workspace builds that provides context about what triggered the build. This field should be exposed in the API, UI, and included in support bundles.

Use Cases

1. Debugging Unexpected Starts: Support teams need to identify if workspaces are being started inadvertently (e.g., by VS Code connecting in the background)
2. Resource Optimization: Understanding start patterns helps optimize for common usage
3. Audit Trail: Provides better visibility into workspace lifecycle events
4. Support Investigations: Simplifies troubleshooting when users report unexpected behavior

Implementation Details

• Add a build_reason field to the workspace build database schema
• Allow clients to set this reason when requesting a workspace build
• Automatically set reasons for system-initiated builds (e.g., autostart)
• Pre-defined reason types could include:
  • user_ssh_connection
  • vscode_connection
  • web_terminal
  • manual_ui_action
  • autostart_schedule
  • api_request

Context

This request was inspired by troubleshooting scenarios and the discovery we don't log the exact method of the start, only the client/worker.

Related Issues

• Hard to tell which parameters caused a failed build #6184 - Similar request for terraform plan output improvement