Your favorite shift management application!
Telemetry Guide
This guide documents the anonymous usage telemetry BetterShift can send, field by field, so a self-hoster can decide whether to turn it on without reading the source. It also covers the diagnostics export and every other outbound request the app makes on its own.
Table of Contents
- What This Is
- Every Field
- What Is Never Collected
- Buckets
- Turning It Off
- Where It Goes
- Other Outbound Requests
- The Diagnostics Export
What This Is
Telemetry is opt-in and off by default. A fresh instance sends nothing until an admin explicitly agrees to it in a one-time consent dialog; declining is a permanent, equally valid answer. When enabled, one payload is sent roughly once a day (with a random 5–30 minute startup delay so a fleet of instances restarting together doesn't all report at the same moment). There is no per-request tracking, no analytics script in the page, and no cookie tied to this — the payload is a single, independently generated snapshot of the instance's own state.
The payload is anonymous in the sense that it carries no names, emails, URLs, or IP addresses (see What Is Never Collected) — it is not anonymous in the sense of being unlinkable to itself: a stable instanceId lets repeated pings from the same instance be grouped over time.
Admins can also send the payload right away with the Send now button in Admin → System Settings instead of waiting for the daily timer. It follows the same rules as the daily send — it only works while telemetry is on, and the consent covers the current schemaVersion — and it does not reset the daily schedule. It is rate limited (default 5 per hour, RATE_LIMIT_TELEMETRY_SEND_REQUESTS / RATE_LIMIT_TELEMETRY_SEND_WINDOW) and leaves an audit-log entry with only the outcome, never the endpoint URL. Every automatic send leaves the same kind of entry (system.telemetry_send), so the last outcome is visible in the audit log even though the timer itself stays silent.
If a future release changes what is collected in a way that needs fresh consent, an instance that previously accepted is asked again once (governed by schemaVersion — see the field table below); an instance that declined is never re-prompted.
Every Field
This table is generated from TelemetryPayload in lib/telemetry/schema.ts — every field the type defines appears below, and nothing else does. Fields under scale are size buckets, not exact counts (see Buckets); the diagnostics export is the only path that ever carries exact numbers, and only on admin request.
| Field | Example | Answers |
|---|---|---|
schemaVersion |
1 |
Which version of this payload's shape was used, so a schema change can be handled or ignored correctly. |
instanceId |
"3f2a9c11-8b7d-4e2a-9c31-7a5e6d2b9f01" or null |
A random id generated once, the first time telemetry is turned on, so repeated pings from the same instance can be grouped. null before an instance has ever opted in. |
sentAt |
"2026-09-19T14:32:07.512Z" |
When this specific payload was generated. |
app.version |
"3.2.0" |
Which release is running. |
app.isDev |
false |
Is this a development build. Dev builds send like any other; the flag only lets the receiving side tell them apart. |
app.migrations |
42 |
How many database migrations have been applied — a rough signal of how current the schema is. |
runtime.node |
"24.4.0" |
Which Node.js version the process is running on. |
runtime.arch |
"x64" |
Which CPU architecture (x64, arm64, …). |
runtime.platform |
"linux" |
Which OS family the process runs on. |
runtime.sqlite |
"3.45.1" |
Which SQLite version the database driver reports. |
runtime.timezone |
"Europe/Berlin" or "unknown" |
The value of the TZ environment variable, if set. |
config.authEnabled |
true |
Is authentication turned on for this instance. |
config.guestAccess |
false |
Is guest (no-login) access allowed. |
config.registrationOpen |
true |
Can new users self-register. |
config.defaultLocale |
"de" |
Which locale the instance defaults to. This is the instance-wide default only — there is deliberately no per-user locale field, because nothing in the app stores one per account. |
config.updateCheckEnabled |
true |
Has this admin turned off the update check described in Other Outbound Requests. |
config.rateLimitOverrides |
2 |
How many RATE_LIMIT_* environment variables are set — a count only, never which ones or what values. |
scale.users |
"6-20" |
Roughly how many user accounts exist. |
scale.calendars |
"1-5" |
Roughly how many calendars exist. |
scale.shifts |
"101-500" |
Roughly how many shifts exist. |
scale.presets |
"6-20" |
Roughly how many shift presets exist. |
scale.notes |
"1-5" |
Roughly how many calendar notes/events exist. |
scale.bundles |
"6-20" |
Roughly how many permission bundles exist across all calendars. |
scale.shares |
"1-5" |
Roughly how many calendar shares (invited users) exist. |
scale.accessTokens |
"0" |
Roughly how many share links (access tokens) exist. |
scale.signups |
"1-5" |
Roughly how many shift signups exist. |
features.externalSyncs |
"0" |
Roughly how many external calendar subscriptions are configured — never which calendars they sync to or their URLs. |
features.calendarViewOverrides |
"1-5" |
Roughly how many calendars pin their own view settings instead of using each viewer's personal one. |
features.customFields.count |
"1-5" |
Roughly how many custom field definitions exist across all calendars. |
features.customFields.types |
["text", "select"] |
Which custom field types are in use — never a field's key or label (see What Is Never Collected). |
features.archivedPresets |
true |
Does at least one archived preset exist. |
features.splitShifts |
false |
Does at least one calendar have split shifts enabled. |
health.uptimeHours |
168 |
How many hours since the Node process last (re)started. |
health.syncRuns24h |
12 |
How many external sync runs completed in the last 24 hours. |
health.syncFailures24h |
0 |
How many of those runs failed. |
What Is Never Collected
Regardless of what's enabled, the payload never contains:
- External sync URLs — they can reveal an employer or organization.
- Calendar, shift, or note names/content.
- Custom field keys or labels — only the field types (see
features.customFields.typesabove). - User names.
- Email addresses.
- IP addresses.
- The instance's hostname or domain.
Buckets
Every count under scale and features.externalSyncs / features.calendarViewOverrides / features.customFields.count is reported as one of six size buckets instead of an exact number, via toBucket() in lib/telemetry/schema.ts:
| Bucket | Range |
|---|---|
0 |
Exactly zero. |
1-5 |
1 to 5. |
6-20 |
6 to 20. |
21-100 |
21 to 100. |
101-500 |
101 to 500. |
500+ |
More than 500. |
The comment in the source is explicit about why: an exact count can make a small instance recognisable (e.g. "exactly 3 users"); a bucket answers the same scale question without doing so.
Turning It Off
Three independent controls, in order of precedence:
TELEMETRY_ENABLED=falsein.env— a hard off. It wins over any stored answer, including a previous "yes": no consent dialog is shown, no daily send ever fires, and the admin toggle described below is disabled (shown as environment-managed). This is the setting for an unattended or scripted deployment where telemetry must never be a question.TELEMETRY_ENABLED=true— the mirror image: a hard on. It also skips the dialog and disables the admin toggle, and wins over a stored "no".- The admin toggle (Admin → System Settings) — only reachable when
TELEMETRY_ENABLEDis unset in the environment. This is what the one-time consent dialog writes to, and it can be flipped again at any time afterwards.
Only the literal values true and false are recognised. Anything else (1, yes, TRUE, …) is treated as false — a hard off that also disables the admin toggle — so a typo fails closed rather than silently turning telemetry on.
TELEMETRY_ENDPOINT (default https://telemetry-bettershift.pantelx.com) lets you point the daily send at your own receiver instead — useful if you'd rather run telemetry-hub/ yourself, or something else entirely that accepts the same JSON body.
Where It Goes
The default endpoint is a small Cloudflare Worker; its source lives in this repository at telemetry-hub/ (excluded from the Docker image — it's deployed separately, not run alongside the app). It:
- Accepts only
POSTrequests up to 16 KB. - Validates the payload against the current schema version (
telemetry-hub/src/schemas/v1.ts). A body that isn't valid JSON is answered with400and one larger than 16 KB with413; a payload that parses but fails validation, or carries an unknown/retiredschemaVersion, is answered with200and discarded. Either way the fire-and-forget sender ignores the status and never retries. - Writes a valid payload as one row into a Cloudflare D1 database (
telemetry-hub/src/targets/d1.ts), with each field going into its own named column rather than the request body being stored as-is, so an unexpected extra field can never leak through. No third party is involved — the data goes to the operator's own Cloudflare account and nowhere else. - Never reads the connecting IP, and the table has no column that could hold one — neither an IP nor a country or city derived from it is stored. The
received_attimestamp on each row is the Worker's own clock, not the instance's. Cloudflare still sees the connecting IP in its own edge logs, as it does for any hosted Worker, but the Worker code never touches it. - Keeps rows indefinitely. There is no expiry job: a ping written today is still there next year, and repeated pings from the same instance accumulate as separate rows linked by
instanceId. Nothing beyond the fields listed above is stored, and there is no request log or queue — a payload the Worker cannot write is simply lost, not retried. - Publishes aggregated statistics on a public page, at
GET /on the hub's URL (https://telemetry-bettershift.pantelx.comby default), with the same figures as JSON atGET /data.json. Both are computed hourly by a scheduled job (src/aggregate.ts) and served from that precomputed result, so the page never queries the raw ping table directly. - Only aggregates appear there — counts and shares grouped across instances. The published data contains no instance id, no raw row, and no per-instance timestamp; the closest thing to a timestamp is
computedAt, the time the hourly job last ran, which is not tied to any individual instance. - There is no small-group threshold. A value reported by only one instance — a Node version nobody else is on, a timezone unique to one deployment — is published as such, with an instance count of
1. An earlier design collapsed small groups into an "other" bucket; the maintainer removed it, since the previous telemetry backend had no such floor either. If you are the only instance reporting a given value, that fact is visible on the public page. The one size limit that does exist is unrelated to this: each breakdown lists at most its 25 largest values and sums the rest into oneremainder-marked entry, purely so a page with an attacker-controlled, unbounded field (custom field types) cannot grow without limit — it is not a privacy measure, and nothing is hidden for being rare. - Distributions count instances that reported within the last 30 days — one vote per instance, from its newest ping in that window. The "reports over time" history on the page covers a longer, 90-day window instead.
schemaVersionstays at1for this change. The page publishes aggregates computed from data instances were already sending; the payload itself is unchanged, so no instance is asked for fresh consent. Deciding whether that is acceptable is exactly what this section is for — an admin who already agreed toschemaVersion: 1should judge that consent against what is written here, not against a version bump that didn't happen.
Other Outbound Requests
Telemetry is not the only request BetterShift makes on its own. Independently of telemetry — and regardless of whether telemetry is enabled — /api/version (and the release list behind /api/releases) polls the public GitHub releases API for this project on a 15-minute server-side cache, to show admins whether a newer version is available.
This has existed before telemetry was added and is controlled separately: the "Check for updates" switch in Admin → System Settings (updateCheckEnabled) turns it off. With it off, no request to GitHub is made. Note that config.updateCheckEnabled in the telemetry payload only reports whether this switch is on — it does not send anything from the GitHub response itself.
The Diagnostics Export
Separately from the daily telemetry send, Admin → System Settings has a diagnostics export: an admin-triggered preview that can be copied or used to pre-fill a GitHub issue.
- It carries the same shape as the telemetry payload, but with exact numbers instead of buckets (
scaleand the numeric parts offeaturesare plain counts), plus two fields the telemetry payload never has:envFlags, the values of a fixed allowlist of environment variables (AUTH_ENABLED,ALLOW_GUEST_ACCESS,ALLOW_USER_REGISTRATION,DEFAULT_LOCALE,TZ,TELEMETRY_ENABLED— seeREPORTABLE_ENVinlib/telemetry/collect.ts, neverprocess.envas a whole), plusTELEMETRY_ENDPOINT, which is reported as"custom"or"default"and never as its actual value — a self-hosted receiver URL can be private and carry a token, and this export is meant for public issues, andmigrationList, the list of applied migration hashes. - It works whether or not telemetry is enabled — it's a local, on-demand preview, never sent anywhere automatically. Only pressing "copy" or "open issue" puts it anywhere, and that's the admin's own action, to their own clipboard or their own browser tab to GitHub.
instanceIdis included in the exported/copied diagnostics only when telemetry is enabled and the admin leaves the separate "include instance id" switch on next to the export. With telemetry off, or that switch off,instanceIdis reported asnullin the export regardless of what's stored.