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 (prompt content, 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 (TBD)

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: The userInfo option controls whether the SDK automatically populates user identity fields (user.*). 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.

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 query params that arrive as an unparsed string, see Cookies and 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 queryParams.

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"] },
    queryParams: { mode: "denyList", terms: ["forwarded", "-ip", "remote-", "via", "-user"] },
  },
})

Cookies and Query Params

Cookies and 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 — the same matching rule and terms used for headers apply to cookie names and query param keys. 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

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

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 body collection is enabled via the httpBodies option (a non-empty array listing one or more body types):

• 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.

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.

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, 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
}

// 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
}

@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) { ... }
}

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" }
}

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;

type HeaderConfig struct {
  Request  *KeyValueCollectionBehavior
  Response *KeyValueCollectionBehavior
}

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

Body Type Collection

SDKs MUST support enabling body collection for specific body types. The option accepts an array of body type strings. An empty or omitted array means no bodies are collected (default).

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 string

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

// HttpBodies: []BodyType — nil/empty = off

# http_bodies: list[str] — e.g., ["incomingRequest"]; empty = off

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

// httpBodies: string[] — e.g., ['incomingRequest']; empty = off

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: false
    cookies?: KeyValueCollectionBehavior,          // default: { mode: "denyList" }
    httpHeaders?: {
      request?: KeyValueCollectionBehavior,        // default: { mode: "denyList" }
      response?: KeyValueCollectionBehavior,       // default: { mode: "denyList" }
    },
    httpBodies?: string[],                         // default: [] (off)
    queryParams?: KeyValueCollectionBehavior,      // default: { mode: "denyList" }
    genAIInputs?: boolean,                         // default: true
    genAIOutputs?: boolean,                        // default: true
    stackFrameVariables?: boolean,                 // default: true
    frameContextLines?: integer,                   // default: 5 (see boolean fallback below)
  },
})