From 4b93b3b0f4f481b45752fdb7432f65bd676f3173 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 25 Apr 2025 16:56:57 +0100 Subject: [PATCH 1/4] Add telemetry docs --- docs/telemetry/index.md | 105 +++++++++++++++++++++++++++++++++++++++ docs/user-guide/index.md | 5 +- 2 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 docs/telemetry/index.md diff --git a/docs/telemetry/index.md b/docs/telemetry/index.md new file mode 100644 index 00000000..734534fa --- /dev/null +++ b/docs/telemetry/index.md @@ -0,0 +1,105 @@ +--- +layout: docs-user-guide +title: Usage Telemetry +slug: telemetry +--- + + +Starting with the 4.1.0 release, Node-RED gathers anonymous usage information once +a day and shares it with the Node-RED team. + +This information is only shared with the Node-RED team once the user has opted +into sharing their information. If the user declines to share their information, +nothing is sent back to the team. + +### Why? + +Historically, the only measures we've had around the size and scale of the Node-RED +user-base have been secondary indicators, such as high-level statistics provided +by npm and docker, or the general level of activity on the community forum. + +This does not give us much useful information to help understand Node-RED usage; +such as what versions of Node.JS are being used, what operating systems are favoured. + + +### What data is collected? + +With the 4.1.0 release, the collected information is: + - A randomly generated instance identifier to allow us to de-duplicate reports + - Node-RED version + - Node.JS version + - OS type/release/architecture + +It does **not** contain: + - Any personal information + - Any flow configuration information + - Any user-specific information related to security + - Any information outside the scope of Node-RED + +### How is the data collected? + +If the user has opted to share information, a task will run 30 minutes after +Node-RED starts (or when they opt-in), and every 24 hours after that. + +The data is sent over HTTPS to an endpoint hosted by the Node-RED project. + +### What happens to the data? + +The reports are aggregated into a daily record of usage. The individual reports +are kept for up to 90 days. + +### Who has access to the data? + +The raw data is only accessible by the core Team Committers. + +The aggregated data will be made available on a public dashboard for public +consumption. _Note_: At the time of writing, we have not yet released this feature, +so we have very little data to start building the dashboard with. Once it is available, +this document will be updated to link to it and it will be publicised within the community. + +### How do I opt out? + +We hope you'll share your information to help us maintain the project. However, +if you want to opt out, there are a number of ways to do so. + +#### Editor Settings + +The first time you open the editor for Node-RED 4.1 or later, if you have not +already opted in or out, you will be asked if you are willing to share your information. + +You can change you made via the Editor Settings dialog at any time. + +#### `settings.js` file + +You can also enable/disable telemetry via your settings file. + +If you have a preexisting settings file, you will need to add a `telemetry` section. +For new installs of Node-RED, the default settings file already has this section, but +with the `enabled` option commented out. Remove the `//` at the start of the line +and change the value to `false`: + +``` + telemetry: { + enabled: false, + /** + * If telemetry is enabled, the editor will notify the user if a new version of Node-RED + * is available. Set the following property to false to disable this notification. + */ + updateNotification: true + }, +``` + +#### Other + +You can also disable telemetry using the `--no-telemetry` command-line flag, or by setting +`NODE_RED_DISABLE_TELEMETRY` environment variable. + +### Update notification + +With the usage telemetry feature enabled, in response to sending the information, Node-RED +is notified when there is a new version available. This will generate a notification +in the editor tp help you know when its time to upgrade. + +This notification can be disabled via the `telemetry.updateNotification` setting in the +settings file; it cannot be disabled from within the editor. + diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 9f24144b..2dc16eb2 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -30,6 +30,10 @@ title: User Guide - [Configuring Node-RED](/docs/user-guide/configuration) - [Command-line Admin](/docs/user-guide/node-red-admin) +### Usage Telemetry + + - [Usage Telemetry](/docs/telemetry) + ### Advanced - [Embedding into an existing app](/docs/user-guide/runtime/embedding) @@ -44,4 +48,3 @@ places you can do so: - Subscribe to the [blog](https://nodered.org/blog/) - Follow us on: - Mastodon: [@nodered@social.nodered.org](https://social.nodered.org/@nodered) - - Twitter: [@nodered](http://twitter.com/nodered) From 9d6764d9622772789e55bf6c969750fff586e566 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 9 May 2025 14:38:15 +0100 Subject: [PATCH 2/4] Update wording around update notifications --- docs/telemetry/index.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/telemetry/index.md b/docs/telemetry/index.md index 734534fa..ca8dc962 100644 --- a/docs/telemetry/index.md +++ b/docs/telemetry/index.md @@ -6,7 +6,8 @@ slug: telemetry Starting with the 4.1.0 release, Node-RED gathers anonymous usage information once -a day and shares it with the Node-RED team. +a day and shares it with the Node-RED team. In return, Node-RED will notify the user +when there is a new version available. This information is only shared with the Node-RED team once the user has opted into sharing their information. If the user declines to share their information, @@ -14,12 +15,20 @@ nothing is sent back to the team. ### Why? +As with all software, it is important to keep it up to date. With legislation +such as the EU's [Cyber Resilience Act](https://digital-strategy.ec.europa.eu/en/library/cyber-resilience-act) +on the horizon, we want to take a proactive approach to help users keep their Node-RED +environments up to date and secure. + +The Usage Telemetry serves two purposes; + +1. It allows us to notify users within the application when there are updates available, +2. It allows us to get a better understanding of Node-RED usage; what versions are being used, what operating systems are favoured. + Historically, the only measures we've had around the size and scale of the Node-RED user-base have been secondary indicators, such as high-level statistics provided -by npm and docker, or the general level of activity on the community forum. - -This does not give us much useful information to help understand Node-RED usage; -such as what versions of Node.JS are being used, what operating systems are favoured. +by npm and docker, or the general level of activity on the community forum. This does +not give us much useful information to help understand Node-RED usage. ### What data is collected? @@ -38,7 +47,7 @@ It does **not** contain: ### How is the data collected? -If the user has opted to share information, a task will run 30 minutes after +If the user has opted to receive update notifications, a task will run 30 minutes after Node-RED starts (or when they opt-in), and every 24 hours after that. The data is sent over HTTPS to an endpoint hosted by the Node-RED project. @@ -59,13 +68,15 @@ this document will be updated to link to it and it will be publicised within the ### How do I opt out? -We hope you'll share your information to help us maintain the project. However, -if you want to opt out, there are a number of ways to do so. +We hope you'll appreciate the value of knowing when there are updates available, and that +by opting in, you'll help us maintain the project. + +However, if you want to opt out, there are a number of ways to do so. #### Editor Settings The first time you open the editor for Node-RED 4.1 or later, if you have not -already opted in or out, you will be asked if you are willing to share your information. +already opted in or out, you will be asked if you are willing to receive update notifications. You can change you made via the Editor Settings dialog at any time. @@ -73,7 +84,7 @@ You can change you made via the Editor Settings dialog at any time. You can also enable/disable telemetry via your settings file. -If you have a preexisting settings file, you will need to add a `telemetry` section. +If you have a pre-existing settings file, you will need to add a `telemetry` section. For new installs of Node-RED, the default settings file already has this section, but with the `enabled` option commented out. Remove the `//` at the start of the line and change the value to `false`: @@ -82,8 +93,9 @@ and change the value to `false`: telemetry: { enabled: false, /** - * If telemetry is enabled, the editor will notify the user if a new version of Node-RED - * is available. Set the following property to false to disable this notification. + * If telemetry is enabled, the runtime will log a message when an update is available. + * The editor will also notify the user if a new version of Node-RED + * is available. Set the following property to false to disable this editor notification. */ updateNotification: true }, @@ -103,3 +115,5 @@ in the editor tp help you know when its time to upgrade. This notification can be disabled via the `telemetry.updateNotification` setting in the settings file; it cannot be disabled from within the editor. +The runtime will also log when an update is available; this cannot be disabled. + From a98879c38f9d31059f5b337ae8a8196112a82b79 Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 9 May 2025 17:21:00 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/telemetry/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/telemetry/index.md b/docs/telemetry/index.md index ca8dc962..76165a7c 100644 --- a/docs/telemetry/index.md +++ b/docs/telemetry/index.md @@ -78,8 +78,7 @@ However, if you want to opt out, there are a number of ways to do so. The first time you open the editor for Node-RED 4.1 or later, if you have not already opted in or out, you will be asked if you are willing to receive update notifications. -You can change you made via the Editor Settings dialog at any time. - +You can change your preference via the Editor Settings dialog at any time. #### `settings.js` file You can also enable/disable telemetry via your settings file. @@ -110,7 +109,7 @@ You can also disable telemetry using the `--no-telemetry` command-line flag, or With the usage telemetry feature enabled, in response to sending the information, Node-RED is notified when there is a new version available. This will generate a notification -in the editor tp help you know when its time to upgrade. +in the editor to help you know when it's time to upgrade. This notification can be disabled via the `telemetry.updateNotification` setting in the settings file; it cannot be disabled from within the editor. From d4a22d17c2b16ea3db55ba146d130a2229a42c7f Mon Sep 17 00:00:00 2001 From: Nick O'Leary Date: Fri, 9 May 2025 17:22:24 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/telemetry/index.md | 2 +- docs/user-guide/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/telemetry/index.md b/docs/telemetry/index.md index 76165a7c..9fc69e38 100644 --- a/docs/telemetry/index.md +++ b/docs/telemetry/index.md @@ -20,7 +20,7 @@ such as the EU's [Cyber Resilience Act](https://digital-strategy.ec.europa.eu/en on the horizon, we want to take a proactive approach to help users keep their Node-RED environments up to date and secure. -The Usage Telemetry serves two purposes; +The Usage Telemetry serves two purposes: 1. It allows us to notify users within the application when there are updates available, 2. It allows us to get a better understanding of Node-RED usage; what versions are being used, what operating systems are favoured. diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 2dc16eb2..9df92e36 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -32,7 +32,7 @@ title: User Guide ### Usage Telemetry - - [Usage Telemetry](/docs/telemetry) +- [Usage Telemetry](/docs/telemetry) ### Advanced