You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 36e3af0
Browse filesBrowse the repository at this point in the historyBrowse files
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.
Copy file name to clipboardExpand all lines: docs/deployment/dashboard.md
+74-1Lines changed: 74 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -78,11 +78,84 @@ An API that cannot reach the router at `ROUTER_RELAY_HOST` answers every test wi
78
78
dashboard API is reachable from elsewhere, turn authentication on or set
79
79
`ROUTER_RELAY_ENABLED=false`.
80
80
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
0 commit comments