Skip to content

docs(data-collection): Define the installation identifier - #20856

Merged
ric-oliv merged 2 commits into
masterfrom
docs/data-collection-installation-identifier
Nov 18, 2026
Merged

ric-oliv merged 2 commits into
masterfrom
docs/data-collection-installation-identifier

Conversation

@ric-oliv

@ric-oliv ric-oliv commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

DESCRIBE YOUR PR

The data collection spec doesn't say whether userInfo covers the installation ID that some SDKs generate and send as user.id, so SDKs have read it both ways. Java keeps the ID independent of userInfo in getsentry/sentry-java#5937, and Cocoa's v10 builds gate it in getsentry/sentry-cocoa#8415. .NET has to pick one in getsentry/sentry-dotnet#5932.

This PR adds an "Installation Identifier" section that writes down what Java does:

  • dataCollection options don't gate the installation identifier. It identifies an installation, not a person.
  • SDKs should generate it at random. They may use an ID the platform provides and scopes to the app, like the console IDs feat: let platforms provide the installation ID sentry-native#2150 allows. They must not use values that identify the device outside the app, like a MAC address or a host name.

It also points the userInfo row, the "Disable User Identity" example and the technical context examples at the new section. The section adds requirements, so the spec moves to 0.18.0.

Why Java's reading:

  • The spec suggests userInfo: false to roughly match sendDefaultPii: false, and sendDefaultPii: false always sent the installation ID.
  • Gating only user.id doesn't keep the ID on the device, because sessions send the same value as did. It would drop the "users affected" counts and protect very little.
  • Every SDK that has shipped already sends it. Only Cocoa's unreleased v10 builds gate it.

I also considered gating it on userInfo, the way Cocoa v10 does. That would need a rule for the session did too, and it would change behavior in every shipped SDK.

For the SDKs, Java already follows this, Cocoa would drop the SDK_V10 gate before v10 ships, and .NET will follow up on its side.

IS YOUR CHANGE URGENT?

  • Urgent deadline (GA date, etc.): YYYY-MM-DD
  • Other deadline: YYYY-MM-DD
  • No deadline: Not urgent, can wait up to 1 week+

SDKs disagree on whether `userInfo` gates the installation ID they send
as `user.id`. Write down that `dataCollection` options don't gate it and
that SDKs must generate it at random instead of deriving it from
hardware or system values. Bump the spec to 0.18.0.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
develop-docs Ready Ready Preview Nov 17, 2026 3:30pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
sentry-docs Ignored Ignored Preview Nov 17, 2026 3:30pm UTC

Request Review

@github-actions github-actions Bot added sdk-develop-docs PRs touching develop-docs/sdk Priority: Normal Docs review has no urgent deadline labels Nov 17, 2026
@ric-oliv
ric-oliv marked this pull request as ready for review November 17, 2026 15:16
@cursor

cursor Bot commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Getting ready to monitor this change · Rollout details

Status Service Environment
⏳ Getting ready to monitor this change

SDKs should generate the installation identifier at random, but some
platforms provide a stable, pseudonymous ID scoped to the app. Allow
those, and only rule out values that identify the device outside the
app, such as a MAC address or a host name.
jamescrosswell added a commit to getsentry/sentry-dotnet that referenced this pull request Nov 17, 2026
With UserInfo disabled the enricher skips the whole block, so the old
test never exercised the HasUser() check. Running it with UserInfo both
on and off, and no username set, catches a dropped HasUser() check or a
switch to `Username ??=`.

Also note on DataCollectionOptions.UserInfo that the installation ID
still fills SentryUser.Id, per getsentry/sentry-docs#20856.

Refs #5428

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ric-oliv
ric-oliv merged commit c144556 into master Nov 18, 2026
30 checks passed
@ric-oliv
ric-oliv deleted the docs/data-collection-installation-identifier branch November 18, 2026 10:09

This branch was successfully deployed

1 active deployment
Preview – develop-docs — 93999b3c Deployed Nov 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Priority: Normal Docs review has no urgent deadline sdk-develop-docs PRs touching develop-docs/sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants