# Usage Telemetry

The platform shares anonymous usage information with us at FlowFuse. This helps
us understand how the platform is being used, what areas need improvement
and how we should prioritise future work.

Ultimately, it helps us produce a better platform for all its users.

We do not collect:

- Any personally identifiable information. We do store a secure hash of the sending IP address - but the plain value is never stored
- Any specific details of the flows running on the platform.

## Core Telemetry

### Configuring Telemetry

By default, usage telemetry is enabled on the platform. The administrator can
opt-out of sharing information as part of the initial setup, or through the Admin
Settings section of the platform UI.

It is also possible to disable in the `flowforge.yml` configuration file. This
overrides whatever option is set in the Admin Settings UI.

**IMPORTANT: Licensed installations cannot disable telemetry**

```yaml
telemetry:
  enabled: false
```

### Collected Data

The following pieces of information are included in the telemetry sent back to us:

```json
{
  "instanceId": "5db51f99-c6fb-4340-9c19-78adce58cc1b",
  "os": { "type": "Darwin", "release": "20.5.0", "arch": "x64" },
  "env": { "nodejs": "v16.19.1", "flowforge": "1.0.0" },
  "platform": {
    "counts": {
      "users": 6,
      "teams": 5,
      "projects": 4,
      "devices": 9,
      "projectSnapshots": 16,
      "projectTemplates": 7,
      "projectStacks": 2,
      "libraryEntries": 0,
      "sharedLibraryEntries": 2
    },
    "config": {
      "driver": "localfs",
      "broker": {
        "enabled": true
      },
      "fileStore": {
        "enabled": true
      },
      "email": {
        "enabled": false
      }
    },
    "license": {
      "id": "4c105579-782b-4d53-af62-cf7fa69f6b43",
      "type": "DEV"
    }
  }
}
```

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        instanceId
      </code>
    </td>
    
    <td>
      A unique identifier for the FlowFuse instance.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        os
      </code>
    </td>
    
    <td>
      Information about the operating system
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        env
      </code>
    </td>
    
    <td>
      Node.js and FlowFuse versions
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.counts
      </code>
    </td>
    
    <td>
      A snapshot of the number of users, teams, projects (instances), etc, in use on the platform.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.config.driver
      </code>
    </td>
    
    <td>
      Which backend driver is being used
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.config.broker.enabled
      </code>
    </td>
    
    <td>
      A flag indicating whether the the internal comms broker is enabled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.config.fileStore.enabled
      </code>
    </td>
    
    <td>
      A flag indicating whether the file store is enabled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.config.email.enabled
      </code>
    </td>
    
    <td>
      A flag indicating whether email is enabled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.license.id
      </code>
    </td>
    
    <td>
      The ID of the license loaded
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        platform.license.type
      </code>
    </td>
    
    <td>
      The type of the license
    </td>
  </tr>
</tbody>
</table>

When the data is collected, we also store the timestamp the data was received and
a **hash** of the sending IP address - we do not store the plain value.

### Schedule

For the core tracking, the platform will send the telemetry data:

- 30 seconds after the platform starts up (but only if the platform has already been initialised)
- Once every 24 hours at a time randomly picked when the platform starts

The data is sent via an HTTP Post to `https://ping.flowforge.com`.

## Frontend Telemetry

The FlowFuse UI can be configured to track usage to help understand how users are navigating the pages.

It supports integration with two different services:

- [PostHog](https://posthog.com/) *(recommended)*: You will require your own API key to pass into the `yml`, which will begin the logging of user interactions.
- [Sentry](https://sentry.io/) *(recommended)*: You will need to specify your Sentry DSN for the frontend and back-end
- [Plausible](https://plausible.io/): *(deprecated since 0.9 and will be removed in the future)*: You can setup your own account, and pass the relevant domain to the `yml` in the telemetry configuration. As this option is deprecated, details of how to configure are no longer provided.

### Configuring Telemetry

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        telemetry.enabled
      </code>
    </td>
    
    <td>
      Enables the anonymous usage telemetry of the platform. Default: <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        telemetry.backend.sentry.dsn
      </code>
    </td>
    
    <td>
      The API key provided to you from your own sentry account. Default: <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        telemetry.frontend.posthog.apikey
      </code>
    </td>
    
    <td>
      The API key provided to you from your own PostHog account. Default: <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        telemetry.frontend.posthog.capture_pageview
      </code>
    </td>
    
    <td>
      FlowFuse is designed as to provide custom posthog <code>
        $pageview
      </code>
      
       events that provide more detail on navigation than the default, and suit a single page application better. As such, we recommend setting this to false in order to prevent duplicate <code>
        pageleave
      </code>
      
      /<code>
        pageview
      </code>
      
       events firing. Default: <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        telemetry.frontend.sentry.dsn
      </code>
    </td>
    
    <td>
      The API key provided to you from your own sentry account. Default: <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        telemetry.frontend.sentry.production_mode
      </code>
    </td>
    
    <td>
      Should this instance be treated as production (lower session count recorded). Default: <code>
        false
      </code>
    </td>
  </tr>
</tbody>
</table>

```yaml
telemetry:
  enabled: true
  frontend:
    posthog:
      apikey: <api-key>
      capture_pageview: false
    sentry:
      dsn: <dsn-key>
      production_mode: true
  backend:
    sentry:
      dsn: <dsn-key>
    prometheus:
      enabled: true
```

Sentry reads the environment variable `SENTRY_ENV`, falling back to `NODE_ENV` to set the environment for both frontend and backend.

#### Telemetry During Build

Configure .env with the auth token, org, and project name for the frontend project.

```yaml
# Used for BUILD time sentry reporting
SENTRY_AUTH_TOKEN=
SENTRY_ORG=
SENTRY_PROJECT=
```