Upstream/waveterm
1
0
Fork 0
mirror of https://github.com/wavetermdev/waveterm.git synced 2025-02-28 03:42:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

new telemetry docs (#1999)

Browse Source
This commit is contained in:
Mike Sawka 2025-02-19 15:18:42 -08:00 committed by GitHub
parent ce9775c00c
commit 217ab4a2e3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 209 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
docs/docs/telemetry-old.mdx Normal file
View File

@ -0,0 +1,130 @@
---
id: "telemetry-old"
title: "Legacy Telemetry"
sidebar_class_name: hidden
---
Wave Terminal collects telemetry data to help us track feature use, direct future product efforts, and generate aggregate metrics on Wave's popularity and usage. We do not collect or store any PII (personal identifiable information) and all metric data is only associated with and aggregated using your randomly generated _ClientId_. You may opt out of collection at any time.
If you would like to turn telemetry on or off, the first opportunity is a button on the initial welcome page. After this, it can be turned off by adding `"telemetry:enabled": false` to the `config/settings.json` file. It can alternatively be turned on by adding `"telemetry:enabled": true` to the `config/settings.json` file.
:::info
You can also change your telemetry setting by running the wsh command:
```
wsh setconfig telemetry:enabled=true
```
:::
---
## Sending Telemetry
Provided that telemetry is enabled, it is sent 10 seconds after Waveterm is first booted and then again every 4 hours thereafter. It can also be sent in response to a few special cases listed below. When telemetry is sent, it is grouped into individual days as determined by your time zone. Any data from a previous day is marked as `Uploaded` so it will not need to be sent again.
### Sending Once Telemetry is Enabled
As soon as telemetry is enabled, a telemetry update is sent regardless of how long it has been since the last send. This does not reset the usual timer for telemetry sends.
### Notifying that Telemetry is Disabled
As soon as telemetry is disabled, Waveterm sends a special update that notifies us of this change. See [When Telemetry is Turned Off](#when-telemetry-is-turned-off) for more info. The timer still runs in the background but no data is sent.
### When Waveterm is Closed
Provided that telemetry is enabled, it will be sent when Waveterm is closed.
---
## Telemetry Data
When telemetry is active, we collect the following data. It is stored in the `telemetry.TelemetryData` type in the source code.
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ActiveMinutes | The number of minutes that the user has actively used Waveterm on a given day. This requires the terminal window to be in focus while the user is actively interacting with it. |
| FgMinutes | The number of minutes that Waveterm has been in the foreground on a given day. This requires the terminal window to be in focus regardless of user interaction. |
| OpenMinutes | The number of minutes that Waveterm has been open on a given day. This only requires that the terminal is open, even if the window is out of focus. |
| NumBlocks | The number of existing blocks open on a given day |
| NumTabs | The number of existing tabs open on a given day. |
| NewTab | The number of new tabs created on a given day |
| NumWindows | The number of existing windows open on a given day. |
| NumWS | The number of existing workspaces on a given day. |
| NumWSNamed | The number of named workspaces on a give day. |
| NewTab | The number of new tabs opened on a given day. |
| NumStartup | The number of times waveterm has been started on a given day. |
| NumShutdown | The number of times waveterm has been shut down on a given day. |
| SetTabTheme | The number of times the tab theme is changed from the context menu |
| NumMagnify | The number of times any block is magnified |
| NumPanics | The number of backend (golang) panics caught in the current day |
| NumAIReqs | The number of AI requests made in the current day |
| NumSSHConn | The number of distinct SSH connections that have been made to distinct hosts |
| NumWSLConns | The number of distinct WSL connections that have been made to distinct distros |
| Renderers | The number of new block views of each type are open on a given day. |
| WshCmds | The number of wsh commands of each type run on a given day |
| Blocks | The number of blocks of different view types open on a given day |
| Conn | The number of successful remote connections made (and errors) on a given day |
## Associated Data
In addition to the telemetry data collected, the following is also reported. It is stored in the `telemetry.ActivityType` type in the source code.
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Day | The date the telemetry is associated with. It does not include the time. |
| Uploaded | A boolean that indicates if the telemetry for this day is finalized. It is false during the day the telemetry is associated with, but gets set true at the first telemetry upload after that. Once it is true, the data for that particular day will not be sent up with the telemetry any more. |
| TzName | The code for the timezone the user's OS is reporting (e.g. PST, GMT, JST) |
| TzOffset | The offset for the timezone the user's OS is reporting (e.g. -08:00, +00:00, +09:00) |
| ClientVersion | Which version of Waveterm is installed. |
| ClientArch | This includes the user's operating system (e.g. linux or darwin) and architecture (e.g. x86_64 or arm64). It does not include data for any Connections at this time. |
| BuildTime | This serves as a more accurate version number that keeps track of when we built the version. It has no bearing on when that version was installed by you. |
| OSRelease | This lists the version of the operating system the user has installed. |
| Displays | Display resolutions (added in v0.9.3 to help us understand what screen resolutions to optimize for) |
## Telemetry Metadata
Lastly, some data is sent along with the telemetry that describes how to classify it. It is stored in the `wcloud.TelemetryInputType` in the source code.
| Name | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| UserId | Currently Unused. This is an anonymous UUID intended for use in future features. |
| ClientId | This is an anonymous UUID created when Waveterm is first launched. It is used for telemetry and sending prompts to Open AI. |
| AppType | This is used to differentiate the current version of waveterm from the legacy app. |
| AutoUpdateEnabled | Whether or not auto update is turned on. |
| AutoUpdateChannel | The type of auto update in use. This specifically refers to whether a latest or beta channel is selected. |
| CurDay | The current day (in your time zone) when telemetry is sent. It does not include the time of day. |
## Geo Data
We do not store IP addresses in our telemetry table. However, CloudFlare passes us Geo-Location headers. We store these two header values:
| Name | Description |
| ------------ | ----------------------------------------------------------------- |
| CFCountry | 2-letter country code (e.g. "US", "FR", or "JP") |
| CFRegionCode | region code (often a provence, region, or state within a country) |
---
## When Telemetry is Turned Off
When a user disables telemetry, Waveterm sends a notification that their anonymous _ClientId_ has had its telemetry disabled. This is done with the `wcloud.NoTelemetryInputType` type in the source code. Beyond that, no further information is sent unless telemetry is turned on again. If it is turned on again, the previous 30 days of telemetry will be sent.
---
## A Note on IP Addresses
Telemetry is uploaded via https, which means your IP address is known to the telemetry server. We **do not** store your IP address in our telemetry table and **do not** associate it with your _ClientId_.
---
## Previously Collected Telemetry Data
While we believe the data we collect with telemetry is fairly minimal, we cannot make that decision for every user. If you ever change your mind about what has been collected previously, you may request that your data be deleted by emailing us at [support@waveterm.dev](mailto:support@waveterm.dev). If you do, we will need your _ClientId_ to remove it.
---
## Privacy Policy
For a summary of the above, you can take a look at our [Privacy Policy](https://www.waveterm.dev/privacy).

147
docs/docs/telemetry.mdx
View File

@ -1,16 +1,32 @@
---
sidebar_position: 100
title: Telemetry
id: "telemetry"
title: "Telemetry"
---
Wave Terminal collects telemetry data to help us track feature use, direct future product efforts, and generate aggregate metrics on Wave's popularity and usage. We do not collect or store any PII (personal identifiable information) and all metric data is only associated with and aggregated using your randomly generated _ClientId_. You may opt out of collection at any time.
## tl;dr
Wave Terminal collects telemetry data to help us track feature use, direct future product efforts, and generate aggregate metrics on Wave's popularity and usage. We do NOT collect personal information (PII), keystrokes, file contents, AI prompts, IP addresses, hostnames, or commands. We attach all information to an anonymous, randomly generated _ClientId_ (UUID). You may opt out of collection at any time.
Here’s a quick summary of what is collected:
- Basic App/System Info – OS, architecture, app version, update settings
- Usage Metrics – App start/shutdown, active minutes, foreground time, tab/block counts/usage
- Feature Interactions – When you create tabs, run commands, change settings, etc.
- Display Info – Monitor resolution, number of displays
- Connection Events – SSH/WSL connection attempts (but NOT hostnames/IPs)
- AI Commands – Only which AI backend is used (e.g., OpenAI, Claude) – no text or prompts sent
- Error Reports – Crash/panic events with minimal debugging info, but no stack traces or detailed errors
Telemetry can be disabled at any time in settings. If not disabled it is sent on startup, on shutdown, and every 4-hours.
## How to Disable Telemetry
If you would like to turn telemetry on or off, the first opportunity is a button on the initial welcome page. After this, it can be turned off by adding `"telemetry:enabled": false` to the `config/settings.json` file. It can alternatively be turned on by adding `"telemetry:enabled": true` to the `config/settings.json` file.
:::info
:::tip
You can also change your telemetry setting by running the wsh command:
You can also change your telemetry setting (true/false) by running the wsh command:
```
wsh setconfig telemetry:enabled=true
@ -18,7 +34,11 @@ wsh setconfig telemetry:enabled=true
:::
---
:::info
This document outlines the new telemetry system as of v0.11.1. The previous telemetry documentation is still relevant and can be found in our [Legacy Telemetry Documentation](./telemetry-old.mdx), but in general, the new telemetry is a superset of the old.
:::
## Sending Telemetry
@ -36,74 +56,65 @@ As soon as telemetry is disabled, Waveterm sends a special update that notifies
Provided that telemetry is enabled, it will be sent when Waveterm is closed.
---
## Event Types
## Telemetry Data
Below is a list of the event types collected in the new telemetry system. More events are likely to be added in the future.
When telemetry is active, we collect the following data. It is stored in the `telemetry.TelemetryData` type in the source code.
| Event Name | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app:startup` | Logged every time you start the app. Contains basic app information like architecture, version, buildtime, etc. |
| `app:shutdown` | Logged on every shutdown |
| `app:activity` | Logged once per hour of app activity |
| `app:display` | Logged on startup and contains information about size of displays |
| `app:counts` | Logged once per hour when app is active, contains basic counts like number of windows, tabs, workspaces, blocks, etc. |
| `action:magnify` | Logged each time a block is magnified |
| `action:settabtheme` | Logged each time a tab theme is changed |
| `action:runaicmd` | Logged each time an AI request is made (no prompt information or text is sent), only sends "ai:backendtype" to know what type of AI backend is being used (OpenAI, Claude, Gemini, etc.) |
| `action:createtab` | Logged when a new tab is created |
| `action:createblock` | Logged when a new block is created (contains the block view type) |
| `wsh:run` | Logged when a wsh command is executed (contains the command type) |
| `debug:panic` | Logged when a backend (Go) panic happens. Contains a debugging string that can be used to find which panic was hit in our source code. No data is sent |
| `conn:connect` | Logged each time a backend ssh/wsl connection connects (logs the conneciton type, no hostname or IP is sent) |
| `conn:connecterror` | Logged when you try to connect but it fails (logs the connection type, no hostname or IP is set, and no detailed error information is sent) |
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ActiveMinutes | The number of minutes that the user has actively used Waveterm on a given day. This requires the terminal window to be in focus while the user is actively interacting with it. |
| FgMinutes | The number of minutes that Waveterm has been in the foreground on a given day. This requires the terminal window to be in focus regardless of user interaction. |
| OpenMinutes | The number of minutes that Waveterm has been open on a given day. This only requires that the terminal is open, even if the window is out of focus. |
| NumBlocks | The number of existing blocks open on a given day |
| NumTabs | The number of existing tabs open on a given day. |
| NewTab | The number of new tabs created on a given day |
| NumWindows | The number of existing windows open on a given day. |
| NumWS | The number of existing workspaces on a given day. |
| NumWSNamed | The number of named workspaces on a give day. |
| NewTab | The number of new tabs opened on a given day. |
| NumStartup | The number of times waveterm has been started on a given day. |
| NumShutdown | The number of times waveterm has been shut down on a given day. |
| SetTabTheme | The number of times the tab theme is changed from the context menu |
| NumMagnify | The number of times any block is magnified |
| NumPanics | The number of backend (golang) panics caught in the current day |
| NumAIReqs | The number of AI requests made in the current day |
| NumSSHConn | The number of distinct SSH connections that have been made to distinct hosts |
| NumWSLConns | The number of distinct WSL connections that have been made to distinct distros |
| Renderers | The number of new block views of each type are open on a given day. |
| WshCmds | The number of wsh commands of each type run on a given day |
| Blocks | The number of blocks of different view types open on a given day |
| Conn | The number of successful remote connections made (and errors) on a given day |
## Event Properties
## Associated Data
Each event may contain the following properties that are relevant to the particular events.
In addition to the telemetry data collected, the following is also reported. It is stored in the `telemetry.ActivityType` type in the source code.
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Day | The date the telemetry is associated with. It does not include the time. |
| Uploaded | A boolean that indicates if the telemetry for this day is finalized. It is false during the day the telemetry is associated with, but gets set true at the first telemetry upload after that. Once it is true, the data for that particular day will not be sent up with the telemetry any more. |
| TzName | The code for the timezone the user's OS is reporting (e.g. PST, GMT, JST) |
| TzOffset | The offset for the timezone the user's OS is reporting (e.g. -08:00, +00:00, +09:00) |
| ClientVersion | Which version of Waveterm is installed. |
| ClientArch | This includes the user's operating system (e.g. linux or darwin) and architecture (e.g. x86_64 or arm64). It does not include data for any Connections at this time. |
| BuildTime | This serves as a more accurate version number that keeps track of when we built the version. It has no bearing on when that version was installed by you. |
| OSRelease | This lists the version of the operating system the user has installed. |
| Displays | Display resolutions (added in v0.9.3 to help us understand what screen resolutions to optimize for) |
## Telemetry Metadata
Lastly, some data is sent along with the telemetry that describes how to classify it. It is stored in the `wcloud.TelemetryInputType` in the source code.
| Name | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| UserId | Currently Unused. This is an anonymous UUID intended for use in future features. |
| ClientId | This is an anonymous UUID created when Waveterm is first launched. It is used for telemetry and sending prompts to Open AI. |
| AppType | This is used to differentiate the current version of waveterm from the legacy app. |
| AutoUpdateEnabled | Whether or not auto update is turned on. |
| AutoUpdateChannel | The type of auto update in use. This specifically refers to whether a latest or beta channel is selected. |
| CurDay | The current day (in your time zone) when telemetry is sent. It does not include the time of day. |
## Geo Data
We do not store IP addresses in our telemetry table. However, CloudFlare passes us Geo-Location headers. We store these two header values:
| Name | Description |
| ------------ | ----------------------------------------------------------------- |
| CFCountry | 2-letter country code (e.g. "US", "FR", or "JP") |
| CFRegionCode | region code (often a provence, region, or state within a country) |
| Property | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `client:arch` | Wave architecture (darwin, windows, linux) and x64 vs arm64 |
| `client:version` | The Wave version (e.g. v0.11.1) |
| `client:initial_version` | Initial installed wave version |
| `client:buildtime` | The buildtime (more exact wave version) |
| `client:osrelease` | A string representing the version of the OS you're running -- different for darwin, windows, and linux |
| `client:isdev` | True/False if using the dev build |
| `autoupdate:channel` | What auto-update channel you're on (latest vs beta) |
| `autoupdate:enabled` | True/False if auto-updated is enabled |
| `loc:countrycode` | Two character country code (e.g. US, CN, FR, JP) |
| `loc:regioncode` | Two character region code (usually the State or Province within a country) |
| `activity:activeminutes` | For app:activity, a number between 0-60 of how many minutes were active within the hour |
| `activity:fgminutes` | For app:activity, a number between 0-60 of how many minutes Wave was the foreground application |
| `activity:openminutes` | For app:activity, a number between 0-60 of how many minutes Wave was open |
| `action:initiator` | For certain actions logs if the action was initiated by the UI or the backend |
| `debug:panictype` | The string that identifies the panic location within our Go code |
| `block:view` | Type of block, e.g. "preview", "waveai", "term", "sysinfo", etc. |
| `ai:backendtype` | AI backend type (e.g. OpenAI, Gemini, Anthropic, etc.) |
| `wsh:cmd` | The wsh command that was run, e.g. "view", "edit", "run", "editconfig" etc. |
| `wsh:haderror` | True/False whether the wsh command returned an error |
| `conn:conntype` | Type of connnection (ssh / wsl) |
| `display:height` | Height of the main display in px |
| `display:width` | Width of the main display in px |
| `display:dpr` | DPR of the main display |
| `display:count` | How many total displays |
| `display:all` | JSON for all the displays attached (same attributes as above) |
| `count:blocks` | Total number of blocks |
| `count:tabs` | Total number of tabs |
| `count:windows` | Total number of windows |
| `count:workspaces` | Total number of workspaces |
| `count:sshconn` | Total number of SSH connections |
| `count:wslconn` | Total number of WSL connections |
| `count:views` | Counts of the types of blocks (views) |
---