Data Collection

Collected data is grouped into three sensitivity levels. These levels form the organizing principle for dataCollection defaults and user configuration.

1. Technical Context Data

Non-identifying context used for debugging and performance. Examples include, but are not limited to:

• Device and environment context (OS, runtime, non-PII identifiers)
• Performance and error context (stack frames, breadcrumbs, span metadata)
• Framework/routing context where it does not contain PII or secrets
• Generative AI metadata (model name, token counts, tool names, etc.)
• Generative AI inputs and outputs (system instructions, prompt content, tool definitions, completion content)

For the full list of supported context types (device, OS, runtime, app, browser, GPU, culture, cloud resource, memory info, and more), see the Contexts Interface.

2. PII Data

Personally Identifiable Information (PII) or user-linked data. Examples include, but are not limited to:

• Identity (name, email, user ID, username)
• Contact (email, phone number, address)
• IP address
• Cookies and headers that identify the user or session
• HTTP request data or database query parameters (TBD)
• Arguments passed to tasks within a queue

For context types that may carry PII fields (e.g. device_unique_identifier in Device Context, or fields in the User Interface), see the linked specs.

3. Sensitive Data

Credentials and secrets that must never be sent by default. Examples include, but are not limited to:

• Passwords, tokens, API keys, bearer tokens
• Header or cookie values matching known sensitive names (auth, token, secret, password, key, jwt, etc.)

For the canonical list of terms used to detect sensitive values at collection time, see the Sensitive Denylist in this spec.

All data-collection options reside under a single top-level key: dataCollection. Each option has a fixed default and is independent of all other options. Users MAY supply only the options they want to override; the SDK MUST apply the documented defaults for any omitted fields.

SDKs MUST support at least the userInfo option, key-value collection modes, HTTP header collection, body type collection, and Boolean option types defined in Option Types. SDKs MAY omit body types that do not apply to their platform (e.g., a client-only SDK MAY omit "incomingRequest" and "outgoingResponse" from the httpBodies array).

The three sensitivity levels determine whether data is collected by default:

• Technical Context Data: SDKs SHOULD collect this data automatically. This level is not gated by any dataCollection option.
• PII Data: SDKs SHOULD automatically populate user identity fields (user.*) by default. Users can set the userInfo option to false to opt out. See dataCollection Options.
• Sensitive Data: SDKs MUST never send sensitive values through automatic instrumentation. Values for keys matching the denylist MUST be replaced with "[Filtered]"; key names are always retained. Users can use beforeSend (or equivalent) to remove or redact keys if needed. See Sensitive Denylist.

SDK documentation MUST document the default value and behavior of each dataCollection option.

All SDK initialization code snippets (including documentation examples, onboarding flows, and CLI wizard output) MUST include a commented-out dataCollection override that disables userInfo and httpBodies. The comment MUST include a URL linking to the full dataCollection documentation matching the specific platform or guide.

init({
  dsn: "...",
  // To disable sending user data and HTTP bodies, uncomment the line below. For more info visit:
  // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
  // dataCollection: { userInfo: false, httpBodies: [] },
})

init({
  dsn: "...",
  // To disable sending user data and HTTP bodies, uncomment the line below. For more info visit:
  // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
  // dataCollection: { userInfo: false, httpBodies: [] },
})

For key-value data (HTTP headers, cookies, URL query params), key names are always included in the event. SDKs MUST apply a sensitive denylist to decide which values are sent in plaintext and which the SDK replaces with "[Filtered]". The denylist matches on key name. The SDK never removes or redacts keys themselves.

Matching Rule

SDKs MUST perform a partial, case-insensitive match when comparing key names against the denylist. A key is treated as sensitive if any denylist term appears as a substring in the key name (e.g., the term auth matches Authorization and X-Auth-Token).

Sensitive Denylist

The following terms MUST be included in the sensitive denylist and applied to headers, cookie names, and query param keys. For cookies and URL query params that arrive as an unparsed string, see Cookies and URL Query Params.

["auth", "token", "secret", "password", "passwd", "pwd", "key", "jwt", "bearer", "sso", "saml", "csrf", "xsrf", "credentials", "session", "sid", "identity"]

Values for keys that match MUST be replaced with "[Filtered]".

Extended Deny Terms

The sensitive denylist covers credentials and secrets. Some headers additionally carry user-identifying information (IP address, user ID, origin host) without being credentials. If an application is subject to GDPR or similar privacy regulations, users can add these terms via a deny list for cookies, httpHeaders, and urlQueryParams.

The list of case-insensitive, partial-match terms SHOULD be documented in the user documentation of the respective SDK:

["forwarded", "-ip", "remote-", "via", "-user"]

Examples of headers matched by these terms: x-forwarded-for, x-real-ip, cf-connecting-ip, remote-addr, x-user-id.

init({
  dataCollection: {
    httpHeaders: {
      request: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
      response: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
    },
    cookies: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
    urlQueryParams: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
  },
})

init({
  dataCollection: {
    httpHeaders: {
      request: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
      response: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
    },
    cookies: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
    urlQueryParams: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
  },
})

URLs

URL strings in span descriptions follow the format defined in Structuring Data: METHOD scheme://host/path — query strings and fragments are excluded.

The urlQueryParams option controls query parameter filtering wherever query strings appear — including url.full, url.query, and request.query_string. url.path and the span description are unaffected since they never contain query strings. For general data scrubbing rules (variable size limits, structuring for server-side scrubbing), see Data Scrubbing.

Encoded query parameters MUST be stored exactly as they appear in the URL.

Example: Given a request to https://example.com/api/users?token=abc123&q=a%20b%26c&page=5:

Cookies and URL Query Params

Cookies and URL query params may arrive as a single unparsed string (e.g., Cookie: user_session=abc; theme=dark-mode) rather than pre-split key-value pairs. SDKs MAY handle both cases:

When the string can be parsed into individual key-value pairs, apply the denylist per-key.

For cookies: the rules and terms as specified in cookies in the dataCollection configuration apply to cookie names. The SDK replaces values for sensitive keys with "[Filtered]" while keeping non-sensitive values as-is. This selective filtering retains harmless contextual information for debugging while protecting sensitive fields.

For example, a Cookie header parsed into individual cookies:

http.request.header.cookie.user_session: "[Filtered]"   // matches "session" in sensitive denylist
http.request.header.cookie.theme: "dark-mode"           // not sensitive — value sent as-is
http.request.header.set_cookie.theme: "light-mode"      // not sensitive — value sent as-is

http.request.header.cookie.user_session: "[Filtered]"   // matches "session" in sensitive denylist
http.request.header.cookie.theme: "dark-mode"           // not sensitive — value sent as-is
http.request.header.set_cookie.theme: "light-mode"      // not sensitive — value sent as-is

For URL query parameters: the rules and terms as specified in urlQueryParams in the dataCollection configuration apply to query parameters. The SDK replaces values for sensitive keys with "[Filtered]" while keeping non-sensitive values as-is (see URLs).

When individual key-value pairs cannot be extracted (e.g., malformed or opaque cookie string), the entire Cookie or Set-Cookie header value MUST be replaced with "[Filtered]". This value is used as a fallback:

http.request.header.cookie: "[Filtered]"   // fallback: cookie header could not be parsed

http.request.header.cookie: "[Filtered]"   // fallback: cookie header could not be parsed

Unfiltered, raw cookie header values MUST NOT be sent. When in doubt, treat the entire cookie header as sensitive and use the fallback.

Request and Response Bodies

When bodies are collected via the httpBodies option (enabled by default; see Body Type Collection):

• Parseable as JSON or form data: SDKs MAY extract key-value pairs and apply the same denylist rules to keys. Values for matching keys MUST be replaced with "[Filtered]". This allows selective scrubbing while retaining non-sensitive fields.
• Not parseable (raw bodies): The body MUST NOT be attached to the event. When the SDK cannot parse the body into a key-value structure, the entire body MUST be replaced with "[Filtered]".

No built-in option scrubs keys; users who need to hide header or cookie names MUST use beforeSend (or equivalent).

The global dataCollection object is the single source of truth for data collection. SDKs SHOULD NOT require users to configure data collection in multiple places.

However, some integrations collect data that warrants independent control. For example, a Replay integration that captures network requests, or when every AI integration should capture generative AI inputs and outputs case-by-case. These integrations MAY expose their own options for controlling which data they collect. Integrations are not required to use the same option names or structure as the global dataCollection object. They SHOULD use whatever is most natural for their API surface.

When an integration exposes data-collection options, the values set on the integration MUST take precedence over the corresponding global dataCollection values for the data that integration collects.

Session Replay

Session Replay is not gated by dataCollection (or its predecessor sendDefaultPii). It is a privacy-sensitive feature with its own opt-in privacy model — by default it masks all text, images, and user input — which is the opposite of the dataCollection opt-out model. Wiring the two together would flip privacy-sensitive defaults for the majority of existing Replay users and create confusion about which layer controls masking.

Because of this, SDKs MUST NOT change what Session Replay captures based on dataCollection. Replay's masking and network-capture behavior MUST continue to be controlled exclusively by the Replay integration's own privacy options. SDK documentation SHOULD explicitly state that dataCollection does not affect Session Replay so users are not surprised by the exception.

Data explicitly set by the user on the scope (user, request, response, tags, contexts, etc.) or on a span, log, or other telemetry is not gated by dataCollection. It MUST always be attached to outgoing telemetry. This also applies to data provided via beforeSend or event processors.

SDKs SHOULD only replace sensitive values with "[Filtered]" when the data is gathered automatically through instrumentation. If the user explicitly provides data (e.g., by setting a request object on the scope), the SDK MUST NOT modify it; the user is responsible for the data they attach.

Users can register callbacks (e.g., beforeSend, event processors) to remove or redact any data (including keys) before events are sent. This spec does not replace those hooks; they remain the primary mechanism for custom filtering and key removal.

Scope Data: Write-Time Gating, Not Read-Time Gating

dataCollection (and its predecessor sendDefaultPii) guards writing data to the scope through auto-instrumentation. It does not guard reading data from the scope when attaching it to outgoing telemetry (events, logs, metrics, etc.).

Concretely:

• Auto-instrumentation writes to scope — When SDK instrumentation automatically populates scope data (e.g., inferring user.ip_address from an HTTP request), the write MUST be gated by the relevant dataCollection option (e.g., userInfo). If the option is disabled, the SDK MUST NOT write that data to the scope.
• Reading from scope to attach to telemetry — When the SDK reads data already present on the scope to attach it as attributes on logs, metrics, or other telemetry, it MUST NOT re-apply dataCollection gating. The data was already accepted at write time.
• User-set data — Data the user explicitly sets (e.g., via Sentry.setUser(), scope.setTag(), or direct attribute assignment) is never gated by dataCollection. The user has made a deliberate choice to include that data.

This means if a user calls Sentry.setUser({ email: "jane@example.com" }), that email MUST appear on logs, metrics, and events regardless of dataCollection.userInfo or sendDefaultPii. The gate only applies to auto-instrumentation that would populate user fields without the user's explicit action.

Boolean Options — used where data cannot be meaningfully filtered at the key level. The SDK either collects the entire category or skips it.

Key-Value Collection Behavior

For key-value data (cookies, headers, URL query params), key names are always included in the event. SDKs MUST support the following collection modes to control which values are sent in plaintext vs. replaced with "[Filtered]":

DenyList and AllowList modes are mutually exclusive. The type SHOULD make it impossible to set both simultaneously.

Reference type:

struct KeyValueCollectionBehavior {
    mode: "off" | "denyList" | "allowList"  // default: "denyList"
    terms?: string[]  // deny or allow terms depending on mode; omit when mode is "off" or when
                      // using denyList mode with only the built-in denylist
}

struct KeyValueCollectionBehavior {
    mode: "off" | "denyList" | "allowList"  // default: "denyList"
    terms?: string[]  // deny or allow terms depending on mode; omit when mode is "off" or when
                      // using denyList mode with only the built-in denylist
}

// TS SDKs MAY also accept this shorthand union type:
type CollectBehavior = boolean | { allow: string[] } | { deny: string[] };
// true         → { mode: "denyList" }
// false        → { mode: "off" }
// { deny: [] } → { mode: "denyList", terms: [] }
// { allow: [] }→ { mode: "allowList", terms: [] }

// TS SDKs MAY also accept this shorthand union type:
type CollectBehavior = boolean | { allow: string[] } | { deny: string[] };
// true         → { mode: "denyList" }
// false        → { mode: "off" }
// { deny: [] } → { mode: "denyList", terms: [] }
// { allow: [] }→ { mode: "allowList", terms: [] }

type CollectionMode string

const (
    CollectionOff       CollectionMode = "off"
    CollectionDenyList  CollectionMode = "denyList"
    CollectionAllowList CollectionMode = "allowList"
)

type KeyValueCollectionBehavior struct {
    Mode  CollectionMode
    Terms []string // nil = no extra terms
}

type CollectionMode string

const (
    CollectionOff       CollectionMode = "off"
    CollectionDenyList  CollectionMode = "denyList"
    CollectionAllowList CollectionMode = "allowList"
)

type KeyValueCollectionBehavior struct {
    Mode  CollectionMode
    Terms []string // nil = no extra terms
}

@dataclass
class KeyValueCollectionBehavior:
    mode: Literal["off", "denyList", "allowList"] = "denyList"
    terms: list[str] = field(default_factory=list)

@dataclass
class KeyValueCollectionBehavior:
    mode: Literal["off", "denyList", "allowList"] = "denyList"
    terms: list[str] = field(default_factory=list)

public class KeyValueCollectionBehavior {
    public enum Mode { OFF, DENY_LIST, ALLOW_LIST }

    private final Mode mode;
    private final List<String> terms;

    public static KeyValueCollectionBehavior off() { ... }
    public static KeyValueCollectionBehavior denyList(String... extraTerms) { ... }
    public static KeyValueCollectionBehavior allowList(String... terms) { ... }
}

public class KeyValueCollectionBehavior {
    public enum Mode { OFF, DENY_LIST, ALLOW_LIST }

    private final Mode mode;
    private final List<String> terms;

    public static KeyValueCollectionBehavior off() { ... }
    public static KeyValueCollectionBehavior denyList(String... extraTerms) { ... }
    public static KeyValueCollectionBehavior allowList(String... terms) { ... }
}

class KeyValueCollectionBehavior {
    public function __construct(
        public string $mode = 'denyList', // 'off', 'denyList', 'allowList'
        public array $terms = [],
    ) {}
}

class KeyValueCollectionBehavior {
    public function __construct(
        public string $mode = 'denyList', // 'off', 'denyList', 'allowList'
        public array $terms = [],
    ) {}
}

HTTP Header Collection

SDKs MUST allow users to configure request and response header collection independently. Each direction supports the same key-value collection modes described above.

Reference type:

httpHeaders: {
    request?: KeyValueCollectionBehavior   // default: { mode: "denyList" }
    response?: KeyValueCollectionBehavior  // default: { mode: "denyList" }
}

httpHeaders: {
    request?: KeyValueCollectionBehavior   // default: { mode: "denyList" }
    response?: KeyValueCollectionBehavior  // default: { mode: "denyList" }
}

SDKs MAY additionally accept a single KeyValueCollectionBehavior for httpHeaders (applying to both directions) as a language-specific shorthand.

// With type union shorthand (type `CollectBehavior` also used for key-value filtering):
type CollectBehavior = boolean | { allow: string[] } | { deny: string[] };

type HeaderConfig = {
  request?: CollectBehavior;
  response?: CollectBehavior;
};

type HttpHeadersOption = CollectBehavior | HeaderConfig;

// With type union shorthand (type `CollectBehavior` also used for key-value filtering):
type CollectBehavior = boolean | { allow: string[] } | { deny: string[] };

type HeaderConfig = {
  request?: CollectBehavior;
  response?: CollectBehavior;
};

type HttpHeadersOption = CollectBehavior | HeaderConfig;

type HeaderConfig struct {
  Request  *KeyValueCollectionBehavior
  Response *KeyValueCollectionBehavior
}

type HeaderConfig struct {
  Request  *KeyValueCollectionBehavior
  Response *KeyValueCollectionBehavior
}

@dataclass
class HeaderConfig:
  request: KeyValueCollectionBehavior | None = None
  response: KeyValueCollectionBehavior | None = None

@dataclass
class HeaderConfig:
  request: KeyValueCollectionBehavior | None = None
  response: KeyValueCollectionBehavior | None = None

Body Type Collection

SDKs MUST support configuring body collection for specific body types. The option accepts an array of body type strings. An omitted array defaults to all body types valid for the platform; an empty array ([]) collects no bodies and is the explicit opt-out.

Valid body type values: "incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse".

Body collection MAY not support allow/deny filtering. Unlike cookies or headers, body content has no predictable key structure for the SDK to filter at collection time. The entire body is either collected (and scrubbed based on the key if parseable as JSON or form data) or not. Body data can still be redacted in beforeSend or event processors if needed.

type BodyType =
  | "incomingRequest"
  | "outgoingRequest"
  | "incomingResponse"
  | "outgoingResponse";

// SDKs MAY also accept boolean shorthand:
// true  → all body types
// false → [] (off)
type BodyCollectionOption = boolean | BodyType[];

type BodyType =
  | "incomingRequest"
  | "outgoingRequest"
  | "incomingResponse"
  | "outgoingResponse";

// SDKs MAY also accept boolean shorthand:
// true  → all body types
// false → [] (off)
type BodyCollectionOption = boolean | BodyType[];

type BodyType string

const (
    BodyIncomingRequest  BodyType = "incomingRequest"
    BodyOutgoingRequest  BodyType = "outgoingRequest"
    BodyIncomingResponse BodyType = "incomingResponse"
    BodyOutgoingResponse BodyType = "outgoingResponse"
)

// HttpBodies: []BodyType — nil = all valid types (default); empty slice = off

type BodyType string

const (
    BodyIncomingRequest  BodyType = "incomingRequest"
    BodyOutgoingRequest  BodyType = "outgoingRequest"
    BodyIncomingResponse BodyType = "incomingResponse"
    BodyOutgoingResponse BodyType = "outgoingResponse"
)

// HttpBodies: []BodyType — nil = all valid types (default); empty slice = off

# http_bodies: list[str] | None — None = all valid types (default); [] = off; e.g., ["incomingRequest"]

# http_bodies: list[str] | None — None = all valid types (default); [] = off; e.g., ["incomingRequest"]

public enum BodyType {
    INCOMING_REQUEST("incomingRequest"),
    OUTGOING_REQUEST("outgoingRequest"),
    INCOMING_RESPONSE("incomingResponse"),
    OUTGOING_RESPONSE("outgoingResponse");
}
// httpBodies: List<BodyType> — null = all valid types (default); empty = off

public enum BodyType {
    INCOMING_REQUEST("incomingRequest"),
    OUTGOING_REQUEST("outgoingRequest"),
    INCOMING_RESPONSE("incomingResponse"),
    OUTGOING_RESPONSE("outgoingResponse");
}
// httpBodies: List<BodyType> — null = all valid types (default); empty = off

// httpBodies: ?string[] — null = all valid types (default); [] = off; e.g., ['incomingRequest']

// httpBodies: ?string[] — null = all valid types (default); [] = off; e.g., ['incomingRequest']

Filtering Stack Frame Variables

The stackFrameVariables option accepts a Boolean by default (true collects all local variables, false collects none). SDKs MUST also accept a KeyValueCollectionBehavior to filter which variables are sent by name. Filtering follows the same collection modes as Key-Value Collection Behavior, matching against variable names.

Pass the dataCollection option to the SDK's init function. All fields are optional and omitted fields MUST use the documented default.

struct KeyValueCollectionBehavior {
    mode: "off" | "denyList" | "allowList"  // default: "denyList"
    terms?: string[]
}

init({
  dataCollection: {
    userInfo?: boolean,                            // default: true
    cookies?: KeyValueCollectionBehavior,          // default: { mode: "denyList" }
    httpHeaders?: {
      request?: KeyValueCollectionBehavior,        // default: { mode: "denyList" }
      response?: KeyValueCollectionBehavior,       // default: { mode: "denyList" }
    },
    httpBodies?: string[],                         // default: all valid body types
    urlQueryParams?: KeyValueCollectionBehavior,   // default: { mode: "denyList" }
    graphQL?: {
      document?: boolean,                          // default: true
      variables?: boolean,                         // default: true
    },
    genAI?: {
      inputs?: boolean,                            // default: true
      outputs?: boolean,                           // default: true
    },
    databaseQueryData?: boolean,                   // default: true
    queues?: boolean,                              // default: true
    stackFrameVariables?: boolean | KeyValueCollectionBehavior, // default: true
    frameContextLines?: integer,                   // default: 5 (see boolean fallback below)
  },
})

struct KeyValueCollectionBehavior {
    mode: "off" | "denyList" | "allowList"  // default: "denyList"
    terms?: string[]
}

init({
  dataCollection: {
    userInfo?: boolean,                            // default: true
    cookies?: KeyValueCollectionBehavior,          // default: { mode: "denyList" }
    httpHeaders?: {
      request?: KeyValueCollectionBehavior,        // default: { mode: "denyList" }
      response?: KeyValueCollectionBehavior,       // default: { mode: "denyList" }
    },
    httpBodies?: string[],                         // default: all valid body types
    urlQueryParams?: KeyValueCollectionBehavior,   // default: { mode: "denyList" }
    graphQL?: {
      document?: boolean,                          // default: true
      variables?: boolean,                         // default: true
    },
    genAI?: {
      inputs?: boolean,                            // default: true
      outputs?: boolean,                           // default: true
    },
    databaseQueryData?: boolean,                   // default: true
    queues?: boolean,                              // default: true
    stackFrameVariables?: boolean | KeyValueCollectionBehavior, // default: true
    frameContextLines?: integer,                   // default: 5 (see boolean fallback below)
  },
})