Skip to content

VNet docs: Provide clear instructions for getting debug logs#56068

Merged
ravicious merged 5 commits intomasterfrom
r7s/vnet-docs-update
Jun 26, 2025
Merged

VNet docs: Provide clear instructions for getting debug logs#56068
ravicious merged 5 commits intomasterfrom
r7s/vnet-docs-update

Conversation

@ravicious
Copy link
Copy Markdown
Member

We've been dealing with an increased amount of customer tickets regarding VNet. While working through them, I noticed a couple of issues with the docs, specifically the section about submitting a VNet-related issue:

  1. The docs describe how to get VNet logs and then they redirect to Teleport Connect docs page for how to get Connect's logs. The user must read and understand sections from those two pages and then form a plan themselves on what to do to submit a good issue.
  2. The docs first describe how to get the logs and later they mention how to enable debug logs. In practice, the regular logs don't provide enough value for non-trivial issues.
  3. The docs include a lot of information about how logs are stored which is more relevant for Teleport devs than customers.
  4. When I originally wrote that section, I didn't realize that it actually is possible to enable debug logs for VNet on macOS.
  5. The Windows section talks about setting TELEPORT_DEBUG=1 as a system variable which enables debug mode in any Teleport tool on the system.

This PR addresses each of those points:

  1. The section on submitting an issue now includes a step-by-step instructions on how to start Connect and VNet with debug logs. The user can just follow instructions instead of having to understand how Connect and VNet work together.
  2. The docs now explicitly instruct the user to provide debug logs.
  3. There's much less focus on specific aspects of os_log and Event Viewer. The docs describe how to get logs so that they can be submitted with the issue, rather than general instructions on how to browse the logs.
  4. The docs now include info on how to enable debug logs for VNet on macOS.
  5. The Windows section now gives the user commands that enable the debug logs only for the VNet service.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 25, 2025

Amplify deployment status

Branch Commit Job ID Status Preview Updated (UTC)
r7s/vnet-docs-update 5f6fa65 3 ✅SUCCEED r7s-vnet-docs-update 2025-06-26 10:52:36

Comment thread docs/pages/connect-your-client/vnet.mdx Outdated
Comment on lines +230 to +231
{/* `&& exit` at the end of the command is there on purpose so that the user doesn't start Connect
from the admin command prompt. */}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I would work the comment into the preceding paragraph so the user doesn't remove the && exit, e.g.:

debug logs in VNet. The `&& exit` at the end of the command prevents you from starting Connect from the admin command prompt.

@ravicious ravicious enabled auto-merge June 26, 2025 10:46
@ravicious ravicious added this pull request to the merge queue Jun 26, 2025
Merged via the queue into master with commit 6594938 Jun 26, 2025
41 checks passed
@ravicious ravicious deleted the r7s/vnet-docs-update branch June 26, 2025 11:03
@backport-bot-workflows
Copy link
Copy Markdown
Contributor

@ravicious See the table below for backport results.

Branch Result
branch/v17 Failed
branch/v18 Create PR

github-merge-queue Bot pushed a commit that referenced this pull request Jul 22, 2025
* [v17][vnet] feat: TCP dial to SSH targets

Backport #55087 to branch/v17

* [v17][vnet] feat: accept incoming SSH connections

Backport #55155 to branch/v17

* [v17][vnet] feat: forward SSH connections to target

Backport #55156 to branch/v17

* [v17][vnet] feat: write VNet SSH keys to TELEPORT_HOME

Backport #55228 to branch/v17

* [v17][vnet] feat: write OpenSSH-compatible config file for VNet SSH

Backport #55239 to branch/v17

* [v17][vnet] fix: support <hostname>.<leaf-cluster> for VNet SSH

Backport #55688 to branch/v17

* fix BlockUntil API for backport

* [v17][vnet] feat: add "Connect with VNet" button to SSH servers

Backport #55623 to branch/v17

* [v17][vnet] feat: support VNet SSH when cluster name does not match proxy public addr

Backport #55655 to branch/v17

* [v17][vnet] feat: add SSH configuration diagnostic

Backport #55594 to branch/v17

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>

* [v17][vnet] feat: show SSH status in VNet slider

Backport #55755 to branch/v17

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>

* [v17][vnet] feat: support proxy recording mode with VNet SSH

Backport #55788 to branch/v17

* [v17][vnet] feat: support diag checks on windows

Backport #55856 to branch/v17

* [v17] fix: data race in vnet.TestSSH

Backport #55980 to branch/v17

* [v17][vnet] feat: mention SSH on VNet info page

Backport #55973 to branch/v17

* [v17][vnet] feat: serve DNS on IPv4

Backport #55539 to branch/v17

* [v17][vnet] fix: close proxied channel only after data and requests are complete

Backport #56020 to branch/v17

* [v17][vnet] feat: automatic SSH client configuration

Backport #55923 to branch/v17

* VNet docs: Provide clear instructions for getting debug logs (#56068)

* VNet diag notification: Do not show button to open report if there's no workspace selected (#56067)

* VNet diag report: Don't show button in notification if there's no workspace

* Replace deprecated MutableRefObject with RefObject

* Make openReport not depend on value of rootClusterUri

Otherwise the effect that uses setInterval re-runs whenever the user
switches to another workspace.

* [v17][vnet] feat: automatic SSH client configuration in Connect

Backport #55924 to branch/v17

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>
Co-authored-by: Grzegorz Zdunek <grzegorz.zdunek@goteleport.com>

* [v17][vnet] fix: avoid empty host matchers in generated SSH config

Backport #56103 to branch/v17

* avoid t.Context() pre go1.24

* fix cspell lint

* [v17][docs] VNet SSH

Backport #56147 to branch/v17

* [v17][vnet] feat: SSH usage reporting

Backport #56537 to branch/v17

* [v17][vnet] fix: mask default IP route on windows

Backport #56957 to branch/v17

---------

Co-authored-by: Rafał Cieślak <rafal.cieslak@goteleport.com>
Co-authored-by: Grzegorz Zdunek <grzegorz.zdunek@goteleport.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants