Skip to content

Add docs for Connect usage reporting #21294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gzdunek merged 9 commits into from
Feb 8, 2023
Merged

Add docs for Connect usage reporting #21294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bfb8002
Add docs for Connect usage reporting
gzdunek Feb 6, 2023
8cea3fd
reuse telemetry specifics in partial file
Feb 6, 2023
daa8966
copy edits
Feb 6, 2023
1ebe7fe
Apply suggestions from code review
gzdunek Feb 7, 2023
d67d7e9
Add Zac's suggestion
gzdunek Feb 7, 2023
f2757a1
Apply suggestions
gzdunek Feb 7, 2023
a37a840
Merge branch 'master' into gzdunek/connect-usage-reporting-docs
gzdunek Feb 7, 2023
6db1891
Add "Assuming an Access Request"
gzdunek Feb 8, 2023
797bb10
Merge branch 'master' into gzdunek/connect-usage-reporting-docs
gzdunek Feb 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/pages/connect-your-client/teleport-connect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,30 @@ installation directory to the `Path` user environment variable.
</TabItem>
</Tabs>

## Telemetry

(!docs/pages/includes/teleport-connect-telemetry.mdx!)

### Disabling telemetry

If you initially agreed to share telemetry data, but now want to opt out, you need to update the `app_config.json` file:
Copy link
Copy Markdown
Member

@ravicious ravicious Feb 8, 2023

Choose a reason for hiding this comment

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

Does the app need to be closed first? I don't remember if we dump the current config to the file just like we do with app_state.json.

Copy link
Copy Markdown
Contributor Author

@gzdunek gzdunek Feb 8, 2023

Choose a reason for hiding this comment

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

No, it doesn't. The config file is updated only on change.

```json
"usageReporting.enabled": false
```
<Tabs>
<TabItem label="macOS">
The Teleport Connect configuration file is located at `~/Library/Application Support/Teleport Connect/app_config.json`.
</TabItem>
<TabItem label="Linux">
The Teleport Connect configuration file is located at `~/.config/Teleport Connect/app_config.json`.
</TabItem>
<TabItem label="Windows">
The Teleport Connect configuration file is located at `C:\Users\%UserName%\AppData\Roaming\Teleport Connect\app_config.json`.
</TabItem>
</Tabs>

The changes will take effect at the next launch.

## Troubleshooting

Logging out of a cluster, closing the app and logging in again resets all app state related to that
Expand Down
6 changes: 6 additions & 0 deletions docs/pages/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,3 +127,9 @@ are exceeding the usage limits of their license. The reporting library code is

Reach out to `sales@goteleport.com` if you have questions about the commercial
editions of Teleport.

### Teleport Connect

(!docs/pages/includes/teleport-connect-telemetry.mdx!)

If you no longer want to send usage data, see [disabling telemetry](./connect-your-client/teleport-connect.mdx#disabling-telemetry).
21 changes: 21 additions & 0 deletions docs/pages/includes/teleport-connect-telemetry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
When you first start the app, Teleport Connect asks for permission to collect and send telemetry data.
This includes tracking events such as:
- Logging in to a cluster
- Starting an SSH, database, or Kubernetes session
- File transfer during an SSH session
- Creating an Access Request
- Reviewing an Access Request
- Assuming an Access Request

On login, we also collect some device-related data:

- Operating system and its version
- App version
- Processor architecture

Additionally, we ask for a job role (answer is optional).

The full list of events and collected data is defined as [protocol buffer messages in the Teleport source](https://github.com/gravitational/teleport/tree/branch/v(=teleport.major_version=)/proto/prehog/v1alpha/connect.proto).
We do not track the details of those events but merely that the given event took place. Each event includes
the cluster name and user name anonymized with HMAC with the internal cluster ID as the key – it’s impossible for us
to resolve that anonymized token back to a particular cluster or user.