Skip to content

Commit 36e3af0

Browse files
authored
docs(deployment): the dashboard's usage data, its switches and the one host it contacts (MAG-5402) (#110)
* docs(deployment): the dashboard's usage data, its switches and the one host it contacts (MAG-5402) Dashboard 0.71.0 can send how it is used to Mixpanel from the browser: autocapture, masked session replays and heatmaps, loaded only after a signed-in person accepts. The Dashboard page did not mention it, and a self-hosted operator needs to know it is off unless turned on, which settings turn it on, and which host a Content-Security-Policy must allow. * docs(deployment): the usage-data section names every setting, what Mixpanel sees and who holds the token The API hands the project token to every signed-in browser while usage data is on, before the person answers the banner, not only to one that accepted. The section now says so, lists the field-change, submit and dashboard events, the IP address Mixpanel geolocates, where the SDK keeps its state, and that consent holds per account and browser. The variables table adds USAGE_TENANT and USAGE_STAFF_DOMAINS, says the API reads all five at start and that the dashboard's Compose files pass them through, and says MIXPANEL_API_HOST takes https only. The diagram gains the browser's edge to MIXPANEL_API_HOST.
1 parent e273986 commit 36e3af0

1 file changed

Lines changed: 74 additions & 1 deletion

File tree

‎docs/deployment/dashboard.md‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,11 +78,84 @@ An API that cannot reach the router at `ROUTER_RELAY_HOST` answers every test wi
7878
dashboard API is reachable from elsewhere, turn authentication on or set
7979
`ROUTER_RELAY_ENABLED=false`.
8080

81+
## Usage data
82+
83+
Dashboard 0.71.0 and later can send how the dashboard is used to the Mixpanel
84+
project whose token it holds: Magma's, where Magma hosts the dashboard. On a
85+
self-hosted install it is **off**, and you do not need to do anything to keep it
86+
off. Dashboard 0.70.0 sends a smaller set of its own events from the API instead,
87+
under the same settings and the same banner.
88+
89+
It is on only when all of these hold:
90+
91+
| Condition | Setting |
92+
| --- | --- |
93+
| Accounts are on | `AUTH_MODE=enabled` |
94+
| The deployment has it on | `USAGE_ANALYTICS=on`. Unset, it is on where Magma hosts the dashboard (`DEPLOYMENT_MODE=managed`) and off on a self-hosted install (`DEPLOYMENT_MODE` unset or `onprem`). |
95+
| A project token is set | `MIXPANEL_TOKEN` |
96+
| The person at the browser accepted | the consent banner, which asks each account once in each browser |
97+
98+
Until a person accepts, their browser loads no Mixpanel code and keeps nothing
99+
but their answer. **Decline** and the banner's close button send nothing, and the
100+
**Account** page changes the answer later. Another account signing in on the
101+
same browser is asked again, and signing out clears what Mixpanel kept in the
102+
browser. A browser that sends Do Not Track sends nothing either way. The banner
103+
and the Account page link Magma's Privacy Policy and Terms.
104+
105+
After an acceptance, the browser loads Mixpanel's SDK, which ships inside the
106+
dashboard, and sends straight to Mixpanel:
107+
108+
- clicks, page views, scrolling, rage and dead clicks, that a field changed and
109+
that a form was submitted, never what is typed into a field;
110+
- the dashboard's own events: look-ups (their kind, result and time, never what
111+
was looked up), chain and time-range picks, rows and panels opened, and how
112+
long a view takes to load;
113+
- a session replay of the visit, with all text and all inputs masked, and
114+
heatmaps;
115+
- a profile under an opaque per-user id that carries the deployment, the user's
116+
role and whether they are Magma staff, never a name or an email.
117+
118+
Mixpanel also sees the browser's IP address, from which it derives a city and a
119+
country, and the browser and operating system. The SDK keeps its state in the
120+
browser's `localStorage`, `sessionStorage` and IndexedDB; it sets no cookie.
121+
122+
Addresses and element attributes are cleaned in the browser before anything
123+
leaves it, in events and replays alike: a request ID, a hash or a typed value
124+
in an address becomes `:id`, and titles, labels and other attributes that carry
125+
such values are dropped. A link's marketing parameters (`utm_*`, click ids) are
126+
not sent, and the two-factor enrolment screen is never recorded. A replay
127+
upload that cannot be cleaned is not sent.
128+
129+
The API never talks to Mixpanel. It hands the project token to every signed-in
130+
browser while usage data is on, before the person answers the banner. A
131+
Mixpanel project token is public by design: it can send events and read
132+
nothing.
133+
134+
Five settings on the API, read when it starts; the web reads none. The
135+
dashboard's Docker Compose files pass each one through from your shell or
136+
`.env`.
137+
138+
| Variable | Default | What it does |
139+
| --- | --- | --- |
140+
| `USAGE_ANALYTICS` | `on` with `DEPLOYMENT_MODE=managed`, `off` otherwise | Turns usage data on or off. |
141+
| `MIXPANEL_TOKEN` | unset | The project token. Without it usage data is off. |
142+
| `MIXPANEL_API_HOST` | `https://api-eu.mixpanel.com` | The one Mixpanel host the browser contacts: your project's region's API host. `https` only (`http` for a loopback mock); any other value turns usage data off, and the API logs why. |
143+
| `USAGE_TENANT` | `TENANT_ID`, else `unnamed` | The deployment name every event and profile carries. |
144+
| `USAGE_STAFF_DOMAINS` | `magmadevs.com` | Comma-separated email domains whose users are marked as staff. The address itself is never sent. |
145+
146+
!!! note "Behind a Content-Security-Policy or a browser egress allowlist"
147+
With usage data on, allow the `MIXPANEL_API_HOST` (`connect-src` in a CSP). With
148+
it blocked, nothing is sent. No script loads from a Mixpanel CDN.
149+
150+
The full list of what is sent and what never is lives in the dashboard repo's
151+
[`docs/USAGE-DATA.md`](https://github.com/Magma-Devs/smart-router-dashboard/blob/main/docs/USAGE-DATA.md).
152+
81153
## How it fits together
82154

83155
```
84156
browser ──▶ web (:3000) ──▶ api (:8000) ──▶ Prometheus (:9090) ──▶ router (:7779/metrics)
85-
└────────▶ router (:3360, the tests you send)
157+
│ └────────▶ router (:3360, the tests you send)
158+
└──▶ MIXPANEL_API_HOST (usage data, only when it is on and accepted)
86159
```
87160

88161
The dashboard is not in the request path. It is read-only with respect to traffic: it

0 commit comments

Comments
 (0)