docs: Add Windows telemetry opt-out instructions (#21710)
* docs: Add Windows telemetry opt-out instructions * docs: Realign telemetry opt-out doc with new style guide - Add Quick Decision Guide for different installation types - Convert opt-out methods to dropdown sections (details/summary) - Use :::note and :::tip admonitions consistently - Add installation-specific paths table - Improve step-by-step instructions with active language - Add Windows section with PowerShell commands (file + env var) - Add verification section - Direct, user-centric tone throughout * docs: Quality check - align telemetry doc with source code Fixes based on source code verification (analytics.c, anonymous-statistics.sh.in): - Restore quality assurance and usage statistics purposes from original doc - Expand data collected section with comprehensive list from script - Fix macOS paths to distinguish Homebrew vs other installations - Keep Windows section with verified paths (copy_files.ps1:35) - Update opt-out note to match original doc wording - Ensure all claims align with source code behavior Source verification: - Opt-out file: analytics.c:940-949, anonymous-statistics.sh.in:21 - DISABLE_TELEMETRY: analytics.c:944, anonymous-statistics.sh.in:22 - Windows path: packaging/windows/copy_files.ps1:35 - Script location: anonymous-statistics.sh.in reference to plugins dir * docs: Add Windows telemetry opt-out instructions Add documentation for disabling anonymous telemetry on Windows, including: - Windows section with PowerShell commands (file + env var) - Verified Windows path from packaging/windows/copy_files.ps1:35 - Quick Decision Guide for different installation types - Installation-specific paths table with macOS variants - Comprehensive list of data collected from anonymous-statistics.sh.in - Fixed opt-out note to correctly describe script behavior Source verification: - Opt-out file: analytics.c:940-949, anonymous-statistics.sh.in:21 - DISABLE_TELEMETRY: analytics.c:944, anonymous-statistics.sh.in:22 - Windows path: packaging/windows/copy_files.ps1:35 - Script location: anonymous-statistics.sh.in reference to plugins dir * docs: Apply Thiago's review feedback - Add FreeBSD support - Add FreeBSD to Quick Decision Guide - Rename Method 1 to include FreeBSD (Linux/macOS/FreeBSD) - Add FreeBSD-specific path example in Method 1 - Add FreeBSD row to Installation-specific paths table Thiago's comments addressed: - ✓ Add FreeBSD to Quick Decision Guide list - ✓ FreeBSD can use the same file-based instructions - ✓ Add FreeBSD path to installation table
Kanela committed
Feb 5, 2026 at 15:50 UTC
02e1670d513b93845fb5e44b40054cf20005a1ae
1 file changed
+176
-48
docs/netdata-agent/configuration/anonymous-telemetry-events.md
+176
-48
@@ -1,27 +1,25 @@
1
# Anonymous telemetry events
2
3
-By default, Netdata collects anonymous usage information from the open-source monitoring Agent. For events like start, stop, crash, etc. we use our own cloud function in GCP. For frontend telemetry (page views etc.) on the dashboard itself, we use the open-source product analytics platform [PostHog](https://github.com/PostHog/posthog).
3
+By default, Netdata collects anonymous usage information from the open-source monitoring Agent. For events like start, stop, crash, etc., we use our own cloud function in GCP. For frontend telemetry (page views, etc.) on the dashboard itself, we use the open-source product analytics platform [PostHog](https://github.com/PostHog/posthog).
4
5
We are strongly committed to your [data privacy](https://netdata.cloud/privacy/).
6
7
We use the statistics gathered from this information for two purposes:
8
9
-1. **Quality assurance**, to help us understand if Netdata behaves as expected, and to help us classify repeated
10
- issues with certain distributions or environments.
9
+1. **Quality assurance**, to help us understand if Netdata behaves as expected, and to help us classify repeated issues with certain distributions or environments.
10
12
-2. **Usage statistics**, to help us interpret how people use the Netdata Agent in real-world environments, and to help
13
- us identify how our development/design decisions influence the community.
11
+2. **Usage statistics**, to help us interpret how people use the Netdata Agent in real-world environments, and to help us identify how our development/design decisions influence the community.
12
13
Netdata collects usage information via two different channels:
14
15
- **Agent dashboard**: We use the [PostHog JavaScript integration](https://posthog.com/docs/integrations/js-integration) (with sensitive event attributes overwritten to be anonymized) to send product usage events when you access an [Agent's dashboard](/docs/dashboards-and-charts/README.md).
16
- **Agent backend**: The `netdata` daemon executes the [`anonymous-statistics.sh`](https://github.com/netdata/netdata/blob/6469cf92724644f5facf343e4bdd76ac0551a418/daemon/anonymous-statistics.sh.in) script when Netdata starts, stops cleanly, or fails.
17
20
-You can opt out from sending anonymous statistics to Netdata through three different [opt-out mechanisms](#opt-out).
18
+## What data is collected
19
22
-## Agent Dashboard - PostHog JavaScript
20
+### Agent Dashboard - PostHog JavaScript
21
24
-When you kick off an Agent dashboard session by visiting `http://NODE:19999`, Netdata initializes a PostHog session and masks various event attributes.
22
+When you access an Agent dashboard session by visiting `http://NODE:19999`, Netdata initializes a PostHog session and masks various event attributes.
23
24
_Note_: You can see the relevant code in the [dashboard repository](https://github.com/netdata/dashboard/blob/master/src/domains/global/sagas.ts#L107) where the `window.posthog.register()` call is made.
25
@@ -35,58 +33,188 @@ window.posthog.register({
33
})
34
```
35
38
-In the above snippet a Netdata PostHog session is initialized and the `ip`, `current_url`, `pathname` and `host` attributes are set to constant values for all events that may be sent during the session. This way, information like the IP or hostname of the Agent will not be sent as part of the product usage event data.
36
+In the above snippet, a Netdata PostHog session is initialized and the `ip`, `current_url`, `pathname`, and `host` attributes are set to constant values for all events that may be sent during the session. This way, information like the IP or hostname of the Agent will not be sent as part of the product usage event data.
37
40
-We have configured the dashboard to trigger the PostHog JavaScript code only when the variable `anonymous_statistics` is true. The value of this
41
-variable is controlled via the [opt-out mechanism](#opt-out).
38
+We have configured the dashboard to trigger the PostHog JavaScript code only when the variable `anonymous_statistics` is true. The value of this variable is controlled via the [opt-out mechanism](#opt-out).
39
43
-## Agent Backend - Anonymous Statistics Script
40
+### Agent Backend - Anonymous Statistics Script
41
45
-Every time the daemon is started or stopped and every time a fatal condition is encountered, Netdata uses the anonymous
46
-statistics script to collect system information and send it to the Netdata telemetry cloud function via a http call. The information collected for all
47
-events is:
42
+Every time the daemon is started or stopped, and every time a fatal condition is encountered, Netdata uses the anonymous statistics script to collect system information and send it to the Netdata telemetry cloud function via an HTTP call.
43
49
-- Netdata version
50
-- OS name, version, id, id_like
51
-- Kernel name, version, architecture
52
-- Virtualization technology
53
-- Containerization technology
44
+**Information collected for all events:**
45
55
-Furthermore, the FATAL event sends the Netdata process and thread name, along with the source code function, source code
56
-filename and source code line number of the fatal error.
46
+- Netdata version, build information, release channel, install type
47
+- OS name, version, ID, and detection method
48
+- Kernel name, version, and architecture
49
+- Virtualization and containerization technology
50
+- System CPU information (model, vendor, frequency, core count)
51
+- System disk and RAM information (total sizes)
52
+- Netdata configuration (streaming, memory mode, web enabled, HTTPS, etc.)
53
+- Alert counts (normal, warning, critical)
54
+- Chart and metric counts
55
+- Collector information
56
+- Cloud connection status and availability
57
+- Streaming/mirroring configuration
58
58
-Starting with v1.21, we additionally collect information about:
59
+**For FATAL events only:**
60
60
-- Failures to build the dependencies required to use Cloud features.
61
-- Unavailability of Cloud features in an Agent.
62
-- Failures to connect to the Cloud in case the [connection process](/src/claim/README.md) has been completed. This includes error codes
63
- to inform the Netdata team about the reason why the connection failed.
61
+The FATAL event sends the Netdata process and thread name, along with the source code function, source code filename, and source code line number of the fatal error.
62
65
-To see exactly what and how is collected, you can review the script template `daemon/anonymous-statistics.sh.in`. The
66
-template is converted to a bash script called `anonymous-statistics.sh`, installed under the Netdata `plugins
67
-directory`, which is usually `/usr/libexec/netdata/plugins.d`.
63
+:::note
64
69
-## Opt-out
65
+To see exactly what and how is collected, you can review the script template `daemon/anonymous-statistics.sh.in`. The template is converted to a bash script called `anonymous-statistics.sh`, installed under the Netdata `plugins directory`, which is usually `/usr/libexec/netdata/plugins.d`.
66
71
-You can opt out from sending anonymous statistics to Netdata through three different opt-out mechanisms:
67
+:::
68
73
-**Create a file called `.opt-out-from-anonymous-statistics`.** This empty file, stored in your Netdata configuration
74
-directory (usually `/etc/netdata`), immediately stops the statistics script from running, and works with any type of
75
-installation, including manual, offline, and macOS installations. Create the file by running `touch
76
-.opt-out-from-anonymous-statistics` from your Netdata configuration directory.
69
+## Quick Decision Guide
70
78
-**Pass the option `--disable-telemetry` to any of the installer scripts in the [installation
79
-docs](/packaging/installer/README.md).** You can append this option during the initial installation or a manual
80
-update. You can also export the environment variable `DISABLE_TELEMETRY` with a non-zero or non-empty value
81
-(e.g.,: `export DISABLE_TELEMETRY=1`).
71
+**What's your installation type?**
72
83
-When using Docker, **set your `DISABLE_TELEMETRY` environment variable to `1`.** You can set this variable with the following
84
-command: `export DISABLE_TELEMETRY=1`. When creating a container using Netdata's [Docker
85
-image](/packaging/docker/README.md#create-a-new-netdata-agent-container) for the first time, this variable will disable
86
-the anonymous statistics script inside the container.
73
+```
74
+🐧 Linux (standard) → Use Method 1 (File-based)
75
+🖥️ Windows → Use Method 2 (Windows-specific)
76
+🐳 Docker → Use Method 3 (Environment variable)
77
+📦 Manual/Offline → Use Method 1 (File-based)
78
+🔷 FreeBSD → Use Method 1 (File-based)
79
+```
80
+
81
+:::note
82
+
83
+All opt-out methods prevent:
84
+
85
+- The daemon from executing the anonymous statistics script
86
+- The PostHog JavaScript snippet (which remains on the dashboard) from firing and sending any data to Netdata PostHog
87
+
88
+When opt-out is enabled, the anonymous statistics script exits immediately without sending any data.
89
+
90
+:::
91
+
92
+## Opt-out Methods
93
+
94
+<details>
95
+<summary><strong>Method 1: Create opt-out file (Linux/macOS/FreeBSD)</strong></summary><br/>
96
+
97
+**When to use**: Standard Linux installations, FreeBSD, manual installations, macOS, or offline setups.
98
+
99
+**Steps**:
100
+
101
+1. Navigate to your Netdata configuration directory
102
+2. Create an empty file called `.opt-out-from-anonymous-statistics`
103
+
104
+```bash
105
+# Linux
106
+touch /etc/netdata/.opt-out-from-anonymous-statistics
107
+
108
+# FreeBSD
109
+touch /usr/local/etc/netdata/.opt-out-from-anonymous-statistics
110
+```
111
+
112
+:::tip
113
+
114
+This method works for all installation types including FreeBSD, manual, offline, and macOS installations. The file simply needs to exist—the content doesn't matter.
115
+
116
+:::
117
+
118
+</details>
119
+
120
+<details>
121
+<summary><strong>Method 2: Windows</strong></summary><br/>
122
+
123
+**When to use**: Windows Agent installations.
124
+
125
+On Windows, the Netdata configuration directory is located at `C:\Program Files\Netdata\etc\netdata`.
126
+
127
+**Option A: Create opt-out file**
128
+
129
+Run PowerShell as Administrator and execute:
130
+
131
+```powershell
132
+New-Item -Path "C:\Program Files\Netdata\etc\netdata\.opt-out-from-anonymous-statistics" -ItemType File -Force
133
+```
134
+
135
+**Option B: Set environment variable**
136
+
137
+Run PowerShell as Administrator and execute:
138
+
139
+```powershell
140
+[Environment]::SetEnvironmentVariable("DISABLE_TELEMETRY", "1", "Machine")
141
+Restart-Service -Name Netdata
142
+```
143
+
144
+:::note
145
+
146
+After setting the environment variable, restart the Netdata service for the changes to take effect.
147
+
148
+:::
149
+
150
+</details>
151
+
152
+<details>
153
+<summary><strong>Method 3: Docker</strong></summary><br/>
154
+
155
+**When to use**: Container-based deployments.
156
+
157
+Set the `DISABLE_TELEMETRY` environment variable when creating the container:
158
+
159
+```bash
160
+docker run -e DISABLE_TELEMETRY=1 ...
161
+```
162
+
163
+Or using Docker Compose:
164
+
165
+```yaml
166
+environment:
167
+ - DISABLE_TELEMETRY=1
168
+```
169
+
170
+See the [Docker installation guide](/packaging/docker/README.md#create-a-new-netdata-agent-container) for complete configuration.
171
+
172
+</details>
173
+
174
+<details>
175
+<summary><strong>Method 4: Installer scripts</strong></summary><br/>
176
+
177
+**When to use**: Initial installation or manual updates.
178
+
179
+Pass the `--disable-telemetry` flag to any installer script:
180
+
181
+```bash
182
+./netdata-installer.sh --disable-telemetry
183
+```
184
+
185
+Or export the environment variable before running the installer:
186
+
187
+```bash
188
+export DISABLE_TELEMETRY=1
189
+./kickstart.sh
190
+```
191
+
192
+See the [installation documentation](/packaging/installer/README.md) for available installer scripts.
193
+
194
+</details>
195
+
196
+## Installation-specific paths
197
+
198
+| Installation Type | Configuration Directory |
199
+| ----------------- | -------------------------------------- |
200
+| Linux (standard) | `/etc/netdata` |
201
+| Windows | `C:\Program Files\Netdata\etc\netdata` |
202
+| Docker | N/A (use environment variable) |
203
+| macOS (Homebrew) | `/usr/local/etc/netdata` |
204
+| macOS (other) | `/etc/netdata` |
205
+| FreeBSD | `/usr/local/etc/netdata` |
206
+
207
+## Verification
208
+
209
+To confirm that telemetry is disabled:
210
+
211
+1. Check that the `.opt-out-from-anonymous-statistics` file exists in your config directory, **OR**
212
+2. Verify that the `DISABLE_TELEMETRY` environment variable is set
213
+
214
+The Agent dashboard will no longer send PostHog events, and the backend statistics script will not execute.
215
88
-Each of these opt-out processes does the following:
216
+## Related documentation
217
90
-- Prevents the daemon from executing the anonymous statistics script.
91
-- Forces the anonymous statistics script to exit immediately.
92
-- Stops the PostHog JavaScript snippet, which remains on the dashboard, from firing and sending any data to the Netdata PostHog.
218
+- [Installation methods](/packaging/installer/README.md) - Complete installation guides
219
+- [Docker installation](/packaging/docker/README.md) - Container-specific setup
220
+- [Windows installation](/packaging/windows/WINDOWS_INSTALLER.md) - Windows Agent setup