Reword Troubleshooting section in Connect docs#32293
Conversation
| ```code | ||
| ~/Library/Application Support/Teleport Connect/tsh | ||
| ``` | ||
|
|
||
| ```code | ||
| ~/Library/Application Support/Teleport Connect/app_state.json | ||
| ``` |
There was a problem hiding this comment.
Thoughts on this? I wanted to make it easy to copy the paths. I didn't put $ in front since it's not really a shell command. This is how it looks:
There was a problem hiding this comment.
What would you think of adding the relevant removal command and shell prompt in each code snippet? The result should be the same, and this will be a little more convenient for users.
There was a problem hiding this comment.
Right, this would work. I used separate code blocks because I wanted to provide the ability to independently copy just the path to one file or another.
But tbh I was thinking more about myself than our users here. I sometimes have to do some work in a Windows VM and it's convenient to just open the docs and copy the path from there. 😶🌫️
I'm going to list commands here.
github-actions
Bot
requested review from
lsgunn-teleport,
ptgott,
r0mant,
xinding33 and
zmb3
|
🤖 Vercel preview here: https://docs-9vtmx6l1z-goteleport.vercel.app/docs/ver/14.x |
ptgott
left a comment
ptgott
left a comment
There was a problem hiding this comment.
Approved, though I think it would make sense to add removal commands and shell prompts to the code snippets in the first Tabs component within "Troubleshooting".
lsgunn-teleport
left a comment
lsgunn-teleport
left a comment
There was a problem hiding this comment.
a couple of questions for you
| If you encounter a bug which renders the UI partially unusable, resetting app state related to a | ||
| particular cluster might help. To do this, log out of the cluster, close the app and log in again. | ||
|
|
||
| To completely wipe all app state, close the app and remove the internal `tsh` folder and the | ||
| `app_state.json` file. This will log you out of all clusters and clear all remembered tabs and | ||
| connections. |
There was a problem hiding this comment.
| If you encounter a bug which renders the UI partially unusable, resetting app state related to a | |
| particular cluster might help. To do this, log out of the cluster, close the app and log in again. | |
| To completely wipe all app state, close the app and remove the internal `tsh` folder and the | |
| `app_state.json` file. This will log you out of all clusters and clear all remembered tabs and | |
| connections. | |
| If you are unable to connect to a cluster or resource using Teleport Connect, try resetting the app state for the cluster. | |
| To reset the app state: | |
| 1. Log out of the cluster. | |
| 1. Close Teleport Connect. | |
| 1. Open Teleport Connect, then log back in to the cluster. |
What does "partially unusable" mean? What is the symptom the user sees? What does "app" refer to (it seems like "app" refers to Teleport Connect but I'm not sure)? Same question for the next paragraph. I took at swing at it, but I'm not sure if this is what you mean.
| If you encounter a bug which renders the UI partially unusable, resetting app state related to a | |
| particular cluster might help. To do this, log out of the cluster, close the app and log in again. | |
| To completely wipe all app state, close the app and remove the internal `tsh` folder and the | |
| `app_state.json` file. This will log you out of all clusters and clear all remembered tabs and | |
| connections. | |
| To completely wipe all app state: | |
| 1. Close Teleport Connect. | |
| 1. Remove the internal `tsh` folder and the `app_state.json` file to log out of all clusters and clear all remembered tabs and connections. |
There was a problem hiding this comment.
When I originally wrote this section, I was thinking of issues like gravitational/teleport.e#858. So what "partially unusable" really means is that due to actions performed outside of the app, the UI of the app is partially broken and the only way to resolve the issue is to reset app state, either in full or just for a specific cluster.
I don't really know how to put it into words so that it's clear the user shouldn't attempt to do this for all errors.
I think this advice to log out of a cluster or wipe all state would only be useful if some UI code crashes. The symptoms that could be seen by the user would be blank window or "Internal Error" screen. This would typically happen if the app gets into some unforeseen state, for example due to server-side changes as I mentioned or due to the downgrade of the app.
And yeah, "app" refers to Teleport Connect.
I'll try to rewrite this with what's discussed here in mind, thanks!
ravicious
force-pushed
the
ravicious/troubleshooting
branch
from
197d6e0 to
aa03dce
Compare
|
🤖 Vercel preview here: https://docs-2mkvibraa-goteleport.vercel.app/docs/ver/14.x |
|
🤖 Vercel preview here: https://docs-9og8i9a02-goteleport.vercel.app/docs/ver/14.x |
|
Ping @lsgunn-teleport. |
public-teleport-github-review-bot
Bot
removed request for
r0mant and
xinding33
|
🤖 Vercel preview here: https://docs-31xtjuxmu-goteleport.vercel.app/docs/ver/preview |
|
@ravicious See the table below for backport results.
|
4 participants
The first commit makes the paragraph about resetting app state easier to follow. I caught myself reading it and wondering what exactly I meant there.
The second commit brings to attention the existence of the "Open Logs Directory" button which will be added by #32044. This commit should be backported to v14 only.