| 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). |
| 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 issues with certain distributions or environments. |
| 10 | |
| 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 | |
| 18 | ## What data is collected |
| 19 | |
| 20 | ### Agent Dashboard - PostHog JavaScript |
| 21 | |
| 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 | |
| 26 | ```JavaScript |
| 27 | window.posthog.register({ |
| 28 | distinct_id: machineGuid, |
| 29 | $ip: "127.0.0.1", |
| 30 | $current_url: "agent dashboard", |
| 31 | $pathname: "netdata-dashboard", |
| 32 | $host: "dashboard.netdata.io", |
| 33 | }) |
| 34 | ``` |
| 35 | |
| 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 | |
| 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 | |
| 40 | ### Agent Backend - Anonymous Statistics Script |
| 41 | |
| 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 | |
| 44 | **Information collected for all events:** |
| 45 | |
| 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 | |
| 59 | **For FATAL events only:** |
| 60 | |
| 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 | |
| 63 | :::note |
| 64 | |
| 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 | |
| 67 | ::: |
| 68 | |
| 69 | ## Quick Decision Guide |
| 70 | |
| 71 | **What's your installation type?** |
| 72 | |
| 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 | :::note |
| 171 | |
| 172 | You can also use `DO_NOT_TRACK=1` as an alternative to `DISABLE_TELEMETRY=1`. |
| 173 | |
| 174 | ::: |
| 175 | |
| 176 | See the [Docker installation guide](/packaging/docker/README.md#create-a-new-netdata-agent-container) for complete configuration. |
| 177 | |
| 178 | </details> |
| 179 | |
| 180 | <details> |
| 181 | <summary><strong>Method 4: Installer scripts</strong></summary><br/> |
| 182 | |
| 183 | **When to use**: Initial installation or manual updates. |
| 184 | |
| 185 | Pass the `--disable-telemetry` flag to any installer script: |
| 186 | |
| 187 | ```bash |
| 188 | ./netdata-installer.sh --disable-telemetry |
| 189 | ``` |
| 190 | |
| 191 | Or export the environment variable before running the installer: |
| 192 | |
| 193 | ```bash |
| 194 | export DISABLE_TELEMETRY=1 |
| 195 | ./kickstart.sh |
| 196 | ``` |
| 197 | |
| 198 | :::note |
| 199 | |
| 200 | You can also use `DO_NOT_TRACK=1` as an alternative to `DISABLE_TELEMETRY=1` when using Netdata installer scripts. |
| 201 | |
| 202 | ::: |
| 203 | |
| 204 | See the [installation documentation](/packaging/installer/README.md) for available installer scripts. |
| 205 | |
| 206 | </details> |
| 207 | |
| 208 | ## Installation-specific paths |
| 209 | |
| 210 | | Installation Type | Configuration Directory | |
| 211 | | ----------------- | -------------------------------------- | |
| 212 | | Linux (standard) | `/etc/netdata` | |
| 213 | | Windows | `C:\Program Files\Netdata\etc\netdata` | |
| 214 | | Docker | N/A (use environment variable) | |
| 215 | | macOS (Homebrew) | `/usr/local/etc/netdata` | |
| 216 | | macOS (other) | `/etc/netdata` | |
| 217 | | FreeBSD | `/usr/local/etc/netdata` | |
| 218 | |
| 219 | ## Verification |
| 220 | |
| 221 | To confirm that telemetry is disabled: |
| 222 | |
| 223 | 1. Check that the `.opt-out-from-anonymous-statistics` file exists in your config directory, **OR** |
| 224 | 2. Verify that the `DISABLE_TELEMETRY` environment variable is set in the environment used to start the Netdata daemon |
| 225 | |
| 226 | :::note |
| 227 | |
| 228 | If you used `DO_NOT_TRACK=1` with Docker or a Netdata installer script, confirm that it resulted in the `.opt-out-from-anonymous-statistics` file being created. The Agent dashboard will no longer send PostHog events, and the backend statistics script will not execute. |
| 229 | |
| 230 | ::: |
| 231 | |
| 232 | ## Related documentation |
| 233 | |
| 234 | - [Installation methods](/packaging/installer/README.md) - Complete installation guides |
| 235 | - [Docker installation](/packaging/docker/README.md) - Container-specific setup |
| 236 | - [Windows installation](/packaging/windows/WINDOWS_INSTALLER.md) - Windows Agent setup |