docs(sdks): Add spec for dataCollection option to supersede sendDefaultPii

[s1gr1d]

This PR extends the Data Collection spec so it is the single place for what SDKs collect and how they scrub it. It adds concrete denylist behavior, request-body and cookie rules, and pulls in the relevant scrubbing behavior from the Data Handling doc.

• Data Collection spec (/sdk/foundations/client/data-collection/)
  • https://develop-docs-git-sig-data-collection-options.sentry.dev/sdk/foundations/client/data-collection/

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ready	Preview, Comment	Apr 9, 2026 1:18pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ignored	Preview	Apr 9, 2026 1:18pm

[stephanie-anderson]

This page does not exist anymore - we moved the PII related content to
https://develop.sentry.dev/sdk/foundations/data-scrubbing/

[cleptric]

We should include some more general information, such as how we expect the default snippet too like now, which is very minimal and in-line with the behavior of sendDefualtPii.

sentry.init({
  dsn: '...',
})

// or with user information

sentry.init({
  dsn: '...',
  dataCollection: {
    includeUserInfo: true,     
  }
})

and also mention the reasoning of this change. In particular, we should highlight that we now include more context by default, without a change in our position to be privacy first.

[itaybre]

This make sense, but got some questions here

[itaybre]

m: We have some additional filtered headers on cocoa that may be relevant here (https://github.com/getsentry/sentry-cocoa/blob/main/Sources/Swift/Core/Tools/HTTPHeaderSanitizer.swift#L8): X-REAL-IP and REMOTE-ADDR

[s1gr1d]

Thanks, as x-real-ip and remote-addr are not considered "sensitive" but PII, I added those to the list of user-sensitive header snippets 👍

[itaybre]

m: Should the same apply for response bodies? This is (or will be, depends on the SDK) being recorded now for Session Replay

[itaybre]

This configuration is set in SessionReplay configuration, it may be worth aligning there

[s1gr1d]

I included them, but made the distinction that outgoing bodies are only applicable in a server-environment.

[itaybre]

Thanks for the clarification 👍

[itaybre]

h: What about request paths?
Some requests may be identifiable, like /user/USER_ID
Should we have a denylist/allowlist for url paths?

[s1gr1d]

Good question 🤔
What we currently do in JS: When we either know it's a param route, we use the appropriate parametrized route name (e.g. user/:id) as the transaction name but the full URL (e.g. user/123) is still added in the attributes. @cleptric Any opinions on that?

[alexander-alderman-webb]

Thanks for this, global options sound great!
What's the plan to migrate away from integration-level options? Such as recordInputs and recordOutputs in JavaScript AI integrations.

[s1gr1d]

Right now, I specified one option aiAgentMessages for all messages. Do you think it would make sense to split this into aiAgentInputMessages and aiAgendOutputMessages?

[alexander-alderman-webb]

to summarize in-person discussion:

• Once the spec is merged and implemented the integration level options are deprecated, and then removed in the next major of the respective SDKs. For finer controls users must use hooks. cc @nicohrubec
• According to the LLM monitoring RFC we will have two options. See this commit. They are called record_inputs and record_outputs. Translating to global options (and camel case), I propose recordGenerativeAIInputs and recordGenerativeAIOutputs.

[s1gr1d]

Thanks for the suggestion. I'll call them generativeAIInputs and generativeAIOutputs - the record is a bit repetitive as all the options are about "recoding" something.

[philipphofmann]

Thanks a lot for tackling this, @s1gr1d. I have one major, high-level, general concept question we should address before moving forward (#16796 (comment)).

[philipphofmann]

h: I think AI Agent Messages can actually contain PII. I think that should be under PII. We have that under PII in the user-facing docs, see for example Python.

[cleptric]

No, we explicitly want to emit those by default, else our product becomes useless. Also, this is not Pii, this is maybe Pii, and everything is maybe Pii.

[philipphofmann]

Okay, I get that. I'm fine with that, but I think we also need to align our docs because that confused me a bit that it was under PII for Python, for example. But that is out of scope of this PR.

[philipphofmann]

m: I think it would be great to clearly state that these here are just examples, but not a complete list. I think it would be great to add links to references where you can find a complete list, or we add a complete list here and then link from the other places in the doc that this is now here, the spec for the complete list. This applies to all three data tiers.

[cleptric]

What is missing?

[philipphofmann]

The event context payload has way more properties: https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts/

For example: culture context, GPU context, app context (version, permissions, view names), cloud resource context, memory info context, ...

[philipphofmann]

h: The nested config with includeUserInfo cascading into collect defaults confuses me a bit. When I look at cookies: true, I can't tell what actually gets sent without also checking includeUserInfo — the same option behaves differently depending on another flag. For a privacy-sensitive config, I think it's important that users can look at their config and immediately know what's being collected.

I wonder if a flatter approach would work better:

1. A flat list of explicit options — each boolean or string list independently controls exactly what gets sent. No flag changes the behavior of other flags.

2. Presets / factory constructors that return a complete, resolved config:

const config = DataCollection.default();
// { userInfo: false, incomingRequestBody: false,
//   aiAgentMessages: true, stackFrameVariables: true,
//   cookies: ['locale', 'theme'],
//   httpHeaders: ['content-type', 'accept', 'x-request-id'],
//   queryParams: true, ... }

// Tweak individual fields — no surprises
config.userInfo = true;
config.incomingRequestBody = true;
config.httpHeaders.push('x-custom-trace');

init({ dsn: "...", dataCollection: config });

// Or start from a PII-inclusive preset
init({ dsn: "...", dataCollection: DataCollection.withPii() });

Why I think this could be better:

• Transparency: Each option means exactly one thing. No implicit cascades to reason about.
• Debuggability: SDK can log the resolved config at init. Support can ask "what's your config?" and get an unambiguous answer.
• Simpler implementation: SDK devs check one value per data type — no "if includeUserInfo is false, then the effective default for incomingRequestBody is false, unless explicitly overridden" logic.
• Presets handle the common cases: Most users want "default" or "with PII" — the factory gives them that in one call, and they can still tweak individual fields.

The tradeoff is slightly more verbose config for custom setups, but I think the clarity is worth it — especially when "I can't easily tell what's being sent" is a real problem.

[s1gr1d]

As talked offline, this is a good suggestion that makes things more clear. I agree, the approach with "silently" overwriting the collection options can be confusing. I'll try to incorporate this into the spec 👍

[s1gr1d]

I initially had the idea of using presets that can be overwritten. It's the same concept but still a bit clumsy. Could look like this:

init({
  dataCollection: {
    preset: "default", // or "withPii"
    overrides: {
      userInfo: true,
      incomingRequestBody: true,
    },
  },
});

The approach you mentioned (have pre-configured objects) is very straight-forward and easily testable. Users would also be able to re-use the pre-configured options and e.g. filter on them.

Should also be possible with other languages Examples:

• JS/TS: static factory funcs returning plain objects
• Java/C#: DataCollectionConfig.defaultConfig() + builder mutation/copy
• Python: dataclass + classmethods
• Ruby/PHP: hash/array factories

[coolguyzone]

LGTM!

[s1gr1d]

I addressed the feedback, renamed some options and restructured the document a bit. I put a summary of the changes in the description.

[giortzisg]

Thanks for working on this @s1gr1d. The spec makes a lot of sense. Just left a high-level comment.

[giortzisg]

I feel that the Option Types are heavily optimized for Javascript. For statically typed languages this is really hard to implement. I would consider for this section to be kept as a semantic model for how the option types work and leave the implementation details to each SDK.

[s1gr1d]

What are the options that would be hard to implement in Go for example?

[giortzisg]

Union and nullable types in general. In Go we need something like this:

KeyValueCollectionPolicy {
  mode: Off | DenyList | AllowList
  terms: string[]
}

[giortzisg]

Thanks for the changes, LGTM 🚀

[cleptric]

Thanks for working on this!

[cleptric]

Suggested change

	generativeAIInputs?: boolean, // default: true
	generativeAIOutputs?: boolean, // default: true
	genAIInputs?: boolean, // default: true
	genAIOutputs?: boolean, // default: true