Operational Telemetry

SeqDesk can send a small operational heartbeat to SeqDesk.com so the project can count active deployments and see which versions are in use. It is off by default, it must be turned on explicitly per instance, and this page enumerates the payload field by field so you can decide with full information.

If you are evaluating this for a data-protection review, the two facts that usually matter are: the payload contains no personal data and no research data of any kind, and it is pseudonymous per install rather than anonymous, because a stable instance UUID links successive heartbeats from the same deployment.

Exactly what is sent

One JSON POST to the configured endpoint. These are all the fields — there is no free-form extras object and no nested payload beyond what is listed.

Two headers accompany it: User-Agent: SeqDesk/<version>, and X-SeqDesk-Telemetry-Token carrying a 32-byte random token generated alongside the instance UUID. The receiver hashes that token and files the heartbeat under the matching instanceId.

What is not sent

No user accounts, names or email addresses. No sequencing orders, samples, studies, or any metadata about them. No uploaded files, filenames or filesystem paths. No pipeline inputs, outputs or parameters. No hostnames, no facility name, no contact details. No credentials or secrets of any kind — the Webin password, the database URL and the session secret are never read by the telemetry code path.

IP addresses are not stored as telemetry application data by the public receiver.

About the word “anonymous”

The payload is pseudonymous per install. instanceId is stable, so the receiver can tell that this month’s heartbeat came from the same deployment as last month’s, and can therefore track one installation’s version history. It carries nothing that identifies a person or an organisation. If even that is more than your policy allows, leave telemetry off or point it at your own receiver.

When a heartbeat is actually sent

This is the part most often misread. There is no telemetry timer and no telemetry background worker. A heartbeat is attempted as a side effect of an update check, and update checks run when someone opens Settings → Info (/admin/settings) or calls the updates API.

The send is then gated on:

1. Telemetry is enabled.
2. An instance UUID and client token exist — they are generated on first send if telemetry is on.
3. The endpoint parses as an http or https URL.
4. At least intervalHours have elapsed since the last successful send. Otherwise the attempt returns throttled and nothing leaves the host.

The request times out after 5 seconds and every failure is swallowed: a heartbeat can never delay or break an update check. The last status and any error message are stored locally and shown next to the toggle.

Practical consequence: on an instance nobody administers interactively, few or no heartbeats are sent, however the interval is configured.

Interval

intervalHours defaults to 24 and accepts 1 to 168. Saving a value outside that range is rejected with Telemetry interval must be between 1 and 168 hours.

Turning it on

The first time a facility admin opens Settings → Info on an instance where telemetry has never been decided, a green panel appears — Help SeqDesk track version adoption and update status — with Enable telemetry and Keep disabled. Choosing either records the decision and dismisses the panel; Keep disabled does not enable anything.

Afterwards the control lives under Feature Flags on the same page:

Precedence, and how to turn it off

The stored database setting wins over the config file and installer defaults. That is deliberate: an admin’s explicit choice must not be silently reverted by a deployment default on the next restart.

To turn it off for one instance, flip SeqDesk telemetry off under Feature Flags; sending stops immediately.

To guarantee it off across a fleet regardless of what any admin has clicked, set the kill switch and restart:

export SEQDESK_TELEMETRY_DISABLED=true

With that set, the settings loader reports telemetry as disabled no matter what the database or config file says, so sendTelemetryHeartbeat returns disabled before any network access is possible.

Configuring the endpoint and interval

Environment variables:

export SEQDESK_TELEMETRY_ENABLED=true
export SEQDESK_TELEMETRY_INTERVAL_HOURS=24                                       # 1–168
export SEQDESK_TELEMETRY_ENDPOINT="https://seqdesk.org/api/telemetry/heartbeat"

settings.json:

{
  "telemetry": {
    "enabled": true,
    "endpoint": "https://seqdesk.org/api/telemetry/heartbeat",
    "intervalHours": 24
  }
}

Remember that the enabled flag from these sources only applies while the database has no stored choice; the endpoint and interval are read from the database first and fall back to these.

See Environment Variables and Config File Reference.

Self-hosting the receiver

A private deployment that wants adoption visibility without sending anything outside can point telemetry.endpoint at its own collector. Any http or https URL is accepted; an unparseable one falls back to the default endpoint, and an invalid one at send time returns invalid-endpoint without a request.

Your receiver needs to accept a JSON POST with the schema above and read the X-SeqDesk-Telemetry-Token header. The public seqdesk.org receiver stores those fields plus a hash of the token, keyed on instanceId.

Troubleshooting

See also

• Updates & Maintenance — the update check the heartbeat rides along with
• Configuration Sources — the general precedence rules, and telemetry’s exception to them