feat: correlate web terminal sessions by session_id - #27677
Open
aqandrew wants to merge 5 commits into
Open
Conversation
Generate a 16-byte session ID (32-char hex) per web terminal session and attach it to the terminal's requests and client logs, per the connection-log correlation RFC. This is DEVEX-663 and stacks on the coderd tracing middleware change (DEVEX-659). Frontend: - Add generateSessionId and mint one session ID per web terminal page load (TerminalPage) and per AgentsPage terminal panel mount. Unlike the reconnection token, it is not persisted in the URL: a reload is a new session. - Send it on the PTY WebSocket as a session_id query parameter (browsers cannot set the baggage header on a WebSocket handshake). - Send it via W3C baggage on the reconnecting-pty signed-token API request. - Include it in the terminal's connection-error console logs. Backend: - The reconnecting-pty WebSocket handler reads the session_id query parameter, validates it, and attaches it to the request and PTY logs so the WebSocket session correlates. Export tracing.ValidSessionID for reuse.
Contributor
Author
|
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
Co-authored-by: Danielle Maywood <danielle@themaywoods.com>
Co-authored-by: Danielle Maywood <danielle@themaywoods.com>
DanielleMaywood
approved these changes
Jul 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Implements the web terminal client half of the
Connection log collection and correlation RFC
(
DEVEX-663). Generates a per-session correlation ID and attaches it to theweb terminal's requests and client logs so a single session can be traced end
to end.
Changes
Session ID
generateSessionId()util: a 16-byte value encoded as a 32-character hexstring, per RFC requirement 1.
TerminalPageload and onAgentsPageterminal panel mount. Unlike the reconnection token, it is notpersisted in the URL, so a reload (or a new tab) is a new session, matching the
RFC's session definition.
Propagation
via W3C baggage (
baggage: session_id=<hex>), which the DEVEX-659 middlewarereads.
baggageheader on a WebSockethandshake (the codebase already works around this for the session token), so
the ID is sent as a
session_idquery parameter instead. The reconnecting-ptyWebSocket handler reads and validates it and attaches it to the request and PTY
logs.
Client logs
console.errorlogs now includesession_id.Telemetry: the web terminal emits none today, so there is nothing to tag
(confirmed with the issue reporter).
Testing
site: unit tests forgenerateSessionId(format + uniqueness) andterminalWebsocketUrl(query param). UpdatedTerminalPage.test.tsx(mocks thegenerator to a fixed ID and asserts the WebSocket URL includes
session_id).tsc, Biome, and the React Compiler check pass.coderd:go test ./coderd/tracing/...andgo vet ./coderd/workspaceapps/...pass; new
ValidSessionIDexport reused by the PTY handler.Design notes / decision log
reconnecttoken isdeliberately persisted in the URL to survive reloads.
session_idis theopposite: a fresh value per page load, matching the RFC (a reload is a new
session). They are separate identifiers.
instance is a singleton shared by the whole app; a global
baggagedefaultwould tag unrelated requests. The header is attached only to the terminal's
signed-token request.
WebSocketcannot send customheaders, so baggage is impossible on the PTY handshake. The
session_idqueryparameter is the counterpart, read server-side in
workspaceAgentPTY.terminal's own WebSocket handler rather than broadening the shared tracing
middleware to trust query params on every route.
32-char hex string (
tracing.ValidSessionID) before logging, to avoid loggingarbitrary client-controlled input.
AgentsPageis React Compiler optimized(no
useMemo/useCallback), so the panel mints its ID withuseStatelazyinit instead.
connection_logscolumns, Tailnet state-change logging, and the CLI
CODER_TRACE_SESSION_IDenv var.
Opened by Coder Agents on behalf of @aqandrew.