Skip to content

docs: add guide for tracing workspace connections - #31342

Merged
matifali merged 18 commits into
mainfrom
superblink/client-1032-trace-connections
Oct 27, 2026
Merged

matifali merged 18 commits into
mainfrom
superblink/client-1032-trace-connections

Conversation

@matifali

@matifali matifali commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds a Monitoring guide for deployment administrators and platform teams to collect client, coderd, and agent logs, correlate entries by client session ID, and interpret connection and workspace lifecycle fields. Links it from Connection logs and adds it to the docs navigation.

Replaces #30707 under @matifali, carrying forward its changes and review history with accuracy fixes in 052d9e8 and the follow-up prose fixes in 3a777bf and 04feb81.

Resolves CLIENT-1032.

Preview: https://coder.com/docs/@superblink%2Fclient-1032-trace-connections/admin/monitoring/trace-connections

Note

This guide is intended for the 2.39.0 docs under the multi-PR launch exception. Coder Remote 1.17.2 and Toolbox plugin 0.9.5 must be available before merge. At the last source check, the VS Code prefix/release PRs (coder/vscode-coder#1164 and coder/vscode-coder#1165) remained open, and Toolbox 0.9.5 remained a draft release.

Validation

  • Full Markdown and table-format checks passed (525 files).
  • Emdash, docs HTML, manifest, and changed-page Vale checks passed, with zero Vale findings.
  • Docs self-check found no remaining verified blockers; all 28 relative links and procedure word counts passed.
  • Product behavior was source-verified. No live IDE/deployment validation was performed, and the PowerShell example was not executed because pwsh is unavailable.
Review decisions and remaining caveats
  • Keep this as a log-correlation how-to in Monitoring, not a failure-recovery procedure. The introduction and instructions reflect that scope.
  • Omit Coder version pins because the docs are versioned. Readers must match their Coder CLI and workspace agents to the control plane. Keep extension/plugin/Toolbox version requirements because those products release independently.
  • Document log pruning before new-file creation, including modification-time ordering and the coder-*.log pattern; missing connection events can also result from reporting failures.
  • Include Toolbox forwarded-channel session IDs, disambiguate terminal/speedtest logger messages, clarify nonzero command exits, and cover all documented autostop and network_error cases.
  • Follow merged docs(docs): document Toolbox support bundle requirements #31289's Toolbox 3.9.0 prerequisite. The plugin's draft release notes still name 3.7.2; maintainer confirmation is needed before changing that requirement.
  • The optional suggestion for an invocation-level log-retention regression test was not implemented: this is a docs-only correction with no production behavior change.
  • The original dependency timeline and discussion remain on docs: add guide for tracing workspace connections #30707. feat: expose connection duration and client session ID in connection logs #30759 has since merged; the former description's unmerged status is historical.

🤖 This PR was created with the help of Coder Agents, and has been reviewed by my human. 🧑💻

coder Bot and others added 13 commits October 13, 2026 18:51
Correct the agent log location (system temporary directory, CODER_AGENT_LOG_DIR), document the VS Code coder.proxyLogDirectory fallback, and apply wording suggestions.
… connections guide

The agent logs server_shutdown with disconnect_initiator on ssh connection complete, and only the coder ssh log carries build_id, build_reason, and transition. coderd rewrites server_shutdown to workspace_stopped in the connection log when a stop or delete build caused it.
Plugin 0.9.5 requires JetBrains Toolbox 3.9.0, and earlier plugin versions collect only Toolbox logs without a Coder support bundle. Link the Toolbox support bundle section.
@matifali matifali added the experimental Changes that might not necessarily be merged, until its approved to proceed with. label Oct 27, 2026
@matifali matifali self-assigned this Oct 27, 2026
@linear-code

linear-code Bot commented Oct 27, 2026

Copy link
Copy Markdown

CLIENT-1032

@github-actions

github-actions Bot commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@linear-code
linear-code Bot marked this pull request as ready for review October 27, 2026 11:48
@linear-code
linear-code Bot requested a review from nickvigilante as a code owner October 27, 2026 11:48
@matifali matifali removed the experimental Changes that might not necessarily be merged, until its approved to proceed with. label Oct 27, 2026
@matifali
matifali requested a review from fioan89 October 27, 2026 18:55
@matifali
matifali requested a review from EhabY October 27, 2026 18:56
@matifali
matifali merged commit 131d4fc into main Oct 27, 2026
32 checks passed
@matifali
matifali deleted the superblink/client-1032-trace-connections branch October 27, 2026 19:03
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 27, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants