import { TabsGroup, TabsItem } from "@/components/DocsTabs";
import Alert from "@/components/DocsAlert";

# Telemetry

This document presents an overview of the telemetry Firezone collects from your
self-hosted instance and how to disable it.

## Why Firezone collects telemetry

We _rely_ on telemetry to prioritize our roadmap and optimize the engineering
resources we have to make Firezone better for everyone.

The telemetry we collect aims to answer the following questions:

- How many people install, use, and stop using Firezone?
- What features are most valuable, and which ones don’t see any use?
- What functionality needs the most improvement?
- When something breaks, why did it break, and how can we prevent it from
  happening in the future?

## How we collect telemetry

There are three main places where telemetry is collected in Firezone:

1. Package telemetry. Includes events such as install, uninstall, and upgrade.
2. CLI telemetry from `firezone-ctl` commands.
3. Product telemetry associated with the Web portal.

In each of these three contexts, we capture the minimum amount of data necessary
to answer the questions in the section above.

Admin emails are collected **only if** you explicitly opt-in to product updates.
Otherwise, personally-identifiable information is **_never_** collected.

We store telemetry in [PostHog](https://posthog.com) only accessible by the
Firezone team. Here is an example of a telemetry event that is sent from your
instance of Firezone to our telemetry server:

```json
{
  "id": "0182272d-0b88-0000-d419-7b9a413713f1",
  "timestamp": "2022-07-22T18:30:39.748000+00:00",
  "event": "fz_http_started",
  "distinct_id": "1ec2e794-1c3e-43fc-a78f-1db6d1a37f54",
  "properties": {
    "$geoip_city_name": "Ashburn",
    "$geoip_continent_code": "NA",
    "$geoip_continent_name": "North America",
    "$geoip_country_code": "US",
    "$geoip_country_name": "United States",
    "$geoip_latitude": 39.0469,
    "$geoip_longitude": -77.4903,
    "$geoip_postal_code": "20149",
    "$geoip_subdivision_1_code": "VA",
    "$geoip_subdivision_1_name": "Virginia",
    "$geoip_time_zone": "America/New_York",
    "$ip": "52.200.241.107",
    "$plugins_deferred": [],
    "$plugins_failed": [],
    "$plugins_succeeded": ["GeoIP (3)"],
    "distinct_id": "1zc2e794-1c3e-43fc-a78f-1db6d1a37f54",
    "fqdn": "awsdemo.firezone.dev",
    "kernel_version": "linux 5.13.0",
    "version": "0.4.6"
  },
  "elements_chain": ""
}
```

## How to disable telemetry

<Alert
  color="info"
  html={`
We <i>rely</i> on product analytics to make Firezone better for everyone. Leaving
telemetry enabled is the <code>single most valuable contribution</code> you can make to
Firezone’s development. That said, we understand some users have higher
privacy or security requirements and would prefer to disable telemetry
altogether. If that’s you, keep reading.
`}
/>

Telemetry is enabled by default. To completely disable product telemetry:

<TabsGroup>
<TabsItem title="Docker" active>

Set the `TELEMETRY_ENABLED` environment variable to `false` and restart the
`firezone` container.

</TabsItem>
<TabsItem title="Omnibus">

Set the following configuration option to `false` in `/etc/firezone/firezone.rb`
and run `sudo firezone-ctl reconfigure` to pick up the changes.

```ruby
default['firezone']['telemetry']['enabled'] = false
```

</TabsItem>
</TabsGroup>
