Skip to content

Add the Toolbox session ID registry and session-aware logging foundation. - #356

Merged
fioan89 merged 4 commits into
mainfrom
feature/connection-log-collection
Aug 28, 2026
Merged

Add the Toolbox session ID registry and session-aware logging foundation.#356
fioan89 merged 4 commits into
mainfrom
feature/connection-log-collection

Conversation

@fioan89

@fioan89 fioan89 commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Context

The connection correlation requirements ask clients to generate a session ID and propagate it through client logs, Coder API requests, telemetry, and the Coder CLI. This provides one value that can be searched across the full connection lifecycle.
Toolbox has a different lifecycle from IDE-oriented clients. Each workspace and agent pair can have one Toolbox-managed SSH connection, and multiple JetBrains IDEs can be launched through that connection. The SSH connection can start before an IDE, remain active after an IDE closes, span multiple IDE launches, or exist without the user launching an IDE at all.
Because of this, a Toolbox session is associated with the workspace and agent connection rather than an individual IDE process. Its session ID remains stable across IDE launches and transient SSH reconnections, and is removed when the Toolbox environment is disposed.

Toolbox requirements

For Toolbox, we need to:

  • Generate a 16-byte session ID encoded as 32 lowercase hexadecimal characters.
  • Associate one session ID with each active workspace and agent pair.
  • Add client_session_id to Toolbox logs related to that session.
  • Attach the ID to Coder API requests using baggage.
  • Pass the ID to the Coder SSH command through CODER_TRACE_SESSION_ID.
  • Reuse the ID across managed reconnections and IDE launches belonging to the same Toolbox environment.
  • Keep deployment-level operations sessionless. If an operation affects several sessions, emit a correlated log for each affected session.

What this PR provides

This PR adds the foundation for these requirements:

  • A process-local, thread-safe session ID registry keyed by workspace and agent name.
  • Session ID generation in the required format.
  • Stable ID reuse for the lifetime of a Toolbox environment.
  • Explicit lookup that does not accidentally create a session.
  • Removal intended only for environment disposal, not IDE shutdown or SSH reconnection.
  • A single logger supporting both regular and session-aware logging.
  • Session-aware messages include client_session_id=.
  • Existing log-and-show behavior is handled by the same wrapper, including popup creation and error handling.
  • Existing logging call sites now use the wrapper while remaining sessionless until their upstream code supplies a session ID.
  • Tests covering session ID behavior, logging delegation, correlation fields, and popup behavior.

Follow-up work will connect the registry to the SSH lifecycle and propagate the session ID through API baggage, the CLI environment, telemetry, and session-specific log call sites.

This drops support for Toolbox versions older than 3.7.2 but instead provides
new APIs that can give better control and insight to the Coder plugin.
Keep one generated session ID for each workspace and agent pair so SSH reconnects share the same correlation value. Remove the entry only when Toolbox disposes the environment, allowing a later environment to begin a new session.
Add one logger wrapper that preserves existing logging calls and lets callers attach a connection session ID when a message belongs to a workspace session.

Keep the existing log-and-show behavior in the same wrapper so messages are logged before they are displayed to the user.
Expose the Coder logger from the shared plugin context and use it for existing log-and-show calls.

Keep popup creation and error handling inside the logger so callers use one place for logging and user notifications.
@fioan89
fioan89 requested review from code-asher, jeremyruppel and matifali and removed request for code-asher August 27, 2026 21:24

@jeremyruppel jeremyruppel left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks great! 👍

@code-asher code-asher left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome!

@fioan89
fioan89 merged commit d90c422 into main Aug 28, 2026
6 checks passed
@fioan89
fioan89 deleted the feature/connection-log-collection branch August 28, 2026 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants