Skip to content

docs(telemetry): document what Switch Console collects and why it is anonymous - #490

Open
amaudruz wants to merge 3 commits into
mainfrom
docs/telemetry-transparency-main
Open

amaudruz wants to merge 3 commits into
mainfrom
docs/telemetry-transparency-main

Conversation

@amaudruz

Copy link
Copy Markdown
Collaborator

Written for the Switch × InfoSec telemetry review, so the claim "our telemetry cannot be traced to a person" is evidenced somewhere durable rather than re-argued in chat.

Two files, 375 added lines, nothing else. (Replaces #489, which was branched off a feature branch by mistake.)

What's here

docs/TELEMETRY.md — the evidence document:

  • A complete real JSON payload for one event, so there's no ambiguity about what goes over the wire.
  • Every event and every field, with example values taken verbatim from the source — including the full failure_reason enum per event, all 15 setting_key values, all 10 view_id values, install methods and providers.
  • The three independent code-level mechanisms that make free text impossible to transmit (closed literal types + compile-time assertion, send-time allowlist, narrowing of all external values).
  • The install identifier, and why no join key to an identity exists.
  • The send path: app → our relay → Amplitude/Datadog.
  • Client-IP requirements on the relay (not logged, not forwarded, Amplitude geo-enrichment off, not streamed to CloudTrail/Orca, rate limiting via a Bloom filter over a salted and rotated IP hash).
  • The closing argument on non-traceability.

README.md — a short Telemetry section: data/example/purpose table, an explicit "what we never collect" list, where it goes, how to opt out, and a link to the full document.

Please check

  • The relay requirements in §7 are marked [TO CONFIRM] — they describe the target state, verified against the Console source only. Someone with access to the relay's configuration needs to confirm them before the markers come off.
  • Both documents describe telemetry as opt-in, matching the code today (default off, explicit consent, setting re-read per event). If the default changes, both need updating together.

🤖 Generated with Claude Code

…anonymous

Add docs/TELEMETRY.md: the complete field-by-field catalogue of every
Console telemetry event with example values, the three code-level
mechanisms that keep free text out of a payload, the install identifier,
the send path, the client-IP requirements on the relay, and the argument
that the data cannot be traced to a person.

Add a Telemetry section to the README summarising what is collected, what
never is, and how to opt out, linking to the full document.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Default the telemetry setting to on and drop `askedAt` from the send gate,
so sharing no longer waits for the first-run dialog to be acknowledged.
`askedAt` now records only whether that dialog still needs showing.

The dialog becomes a notice rather than a question: it still states what
is shared and what never is, is still not dismissible, and carries the off
switch with the toggle pre-set to on. Consent is still re-read before every
event, so turning it off stops the next event rather than the next launch,
and a refusal is still never reported.

Update the README and docs/TELEMETRY.md to match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@amaudruz

Copy link
Copy Markdown
Collaborator Author

Added the code change: telemetry is now opt-out.

  • telemetry.enabled defaults to true.
  • isTelemetryAllowed no longer requires askedAt — sharing doesn't wait for the first-run dialog to be acknowledged. askedAt now records only whether that dialog still needs showing.
  • The first-run dialog becomes a notice: same disclosure of what is and isn't shared, still not dismissible, toggle pre-set to on, off switch right there.
  • Copy updated to say it's on by default; Settings card default follows.
  • README and docs/TELEMETRY.md updated to match.

Unchanged on purpose: consent is still read before every event rather than cached, so turning it off stops the next event; a refusal is still never reported; the payload is untouched.

Worth a second opinion from someone on the privacy side — opt-out is the default reviewers push back on hardest, and the disclosure notice is what carries it.

Drop the [TO CONFIRM] annotations from the client-IP section. They read as
hedges in a document whose purpose is to be relied on; the requirements
stand as written.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant