Skip to content

Commit f2f6f78

Browse files
knollearyknolleary
authored
Merge pull request #381 from node-red/telemetry
Add telemetry docs
2 parents 846b041 + d4a22d1 commit f2f6f78

File tree

2 files changed

+122
-1
lines changed

2 files changed

+122
-1
lines changed

‎docs/telemetry/index.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
layout: docs-user-guide
3+
title: Usage Telemetry
4+
slug: telemetry
5+
---
6+
7+
8+
Starting with the 4.1.0 release, Node-RED gathers anonymous usage information once
9+
a day and shares it with the Node-RED team. In return, Node-RED will notify the user
10+
when there is a new version available.
11+
12+
This information is only shared with the Node-RED team once the user has opted
13+
into sharing their information. If the user declines to share their information,
14+
nothing is sent back to the team.
15+
16+
### Why?
17+
18+
As with all software, it is important to keep it up to date. With legislation
19+
such as the EU's [Cyber Resilience Act](https://digital-strategy.ec.europa.eu/en/library/cyber-resilience-act)
20+
on the horizon, we want to take a proactive approach to help users keep their Node-RED
21+
environments up to date and secure.
22+
23+
The Usage Telemetry serves two purposes:
24+
25+
1. It allows us to notify users within the application when there are updates available,
26+
2. It allows us to get a better understanding of Node-RED usage; what versions are being used, what operating systems are favoured.
27+
28+
Historically, the only measures we've had around the size and scale of the Node-RED
29+
user-base have been secondary indicators, such as high-level statistics provided
30+
by npm and docker, or the general level of activity on the community forum. This does
31+
not give us much useful information to help understand Node-RED usage.
32+
33+
34+
### What data is collected?
35+
36+
With the 4.1.0 release, the collected information is:
37+
- A randomly generated instance identifier to allow us to de-duplicate reports
38+
- Node-RED version
39+
- Node.JS version
40+
- OS type/release/architecture
41+
42+
It does **not** contain:
43+
- Any personal information
44+
- Any flow configuration information
45+
- Any user-specific information related to security
46+
- Any information outside the scope of Node-RED
47+
48+
### How is the data collected?
49+
50+
If the user has opted to receive update notifications, a task will run 30 minutes after
51+
Node-RED starts (or when they opt-in), and every 24 hours after that.
52+
53+
The data is sent over HTTPS to an endpoint hosted by the Node-RED project.
54+
55+
### What happens to the data?
56+
57+
The reports are aggregated into a daily record of usage. The individual reports
58+
are kept for up to 90 days.
59+
60+
### Who has access to the data?
61+
62+
The raw data is only accessible by the core Team Committers.
63+
64+
The aggregated data will be made available on a public dashboard for public
65+
consumption. _Note_: At the time of writing, we have not yet released this feature,
66+
so we have very little data to start building the dashboard with. Once it is available,
67+
this document will be updated to link to it and it will be publicised within the community.
68+
69+
### How do I opt out?
70+
71+
We hope you'll appreciate the value of knowing when there are updates available, and that
72+
by opting in, you'll help us maintain the project.
73+
74+
However, if you want to opt out, there are a number of ways to do so.
75+
76+
#### Editor Settings
77+
78+
The first time you open the editor for Node-RED 4.1 or later, if you have not
79+
already opted in or out, you will be asked if you are willing to receive update notifications.
80+
81+
You can change your preference via the Editor Settings dialog at any time.
82+
#### `settings.js` file
83+
84+
You can also enable/disable telemetry via your settings file.
85+
86+
If you have a pre-existing settings file, you will need to add a `telemetry` section.
87+
For new installs of Node-RED, the default settings file already has this section, but
88+
with the `enabled` option commented out. Remove the `//` at the start of the line
89+
and change the value to `false`:
90+
91+
```
92+
telemetry: {
93+
enabled: false,
94+
/**
95+
* If telemetry is enabled, the runtime will log a message when an update is available.
96+
* The editor will also notify the user if a new version of Node-RED
97+
* is available. Set the following property to false to disable this editor notification.
98+
*/
99+
updateNotification: true
100+
},
101+
```
102+
103+
#### Other
104+
105+
You can also disable telemetry using the `--no-telemetry` command-line flag, or by setting
106+
`NODE_RED_DISABLE_TELEMETRY` environment variable.
107+
108+
### Update notification
109+
110+
With the usage telemetry feature enabled, in response to sending the information, Node-RED
111+
is notified when there is a new version available. This will generate a notification
112+
in the editor to help you know when it's time to upgrade.
113+
114+
This notification can be disabled via the `telemetry.updateNotification` setting in the
115+
settings file; it cannot be disabled from within the editor.
116+
117+
The runtime will also log when an update is available; this cannot be disabled.
118+

‎docs/user-guide/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ title: User Guide
3030
- [Configuring Node-RED](/docs/user-guide/configuration)
3131
- [Command-line Admin](/docs/user-guide/node-red-admin)
3232

33+
### Usage Telemetry
34+
35+
- [Usage Telemetry](/docs/telemetry)
36+
3337
### Advanced
3438

3539
- [Embedding into an existing app](/docs/user-guide/runtime/embedding)
@@ -44,4 +48,3 @@ places you can do so:
4448
- Subscribe to the [blog](https://nodered.org/blog/)
4549
- Follow us on:
4650
- Mastodon: [@nodered@social.nodered.org](https://social.nodered.org/@nodered)
47-
- Twitter: [@nodered](http://twitter.com/nodered)

0 commit comments

Comments
 (0)