From a75ac5927ea732f7a3fab10ff487dcdb209d6230 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 16:20:08 +0100 Subject: [PATCH 01/12] docs(sdk): Move variable size limits to event-payloads Move the "Variable Size" section from expected-features/data-handling to foundations/transport/event-payloads/ under the existing Size Limits heading, where it naturally belongs alongside envelope size limits. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- .../sdk/expected-features/data-handling.mdx | 21 ------------------- .../transport/event-payloads/index.mdx | 17 +++++++++++++++ 2 files changed, 17 insertions(+), 21 deletions(-) diff --git a/develop-docs/sdk/expected-features/data-handling.mdx b/develop-docs/sdk/expected-features/data-handling.mdx index d7422ebdda3d2..6bde5c3a4464f 100644 --- a/develop-docs/sdk/expected-features/data-handling.mdx +++ b/develop-docs/sdk/expected-features/data-handling.mdx @@ -132,24 +132,3 @@ Sentry.addBreadcrumb({ Additionally all semantic conventions of OpenTelemetry for database spans should be set in the `data` if applicable: https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/ - -## Variable Size - -Fields in the event payload that allow user-specified or dynamic values are restricted in size. This applies to most meta data fields, such as variables in a stack trace, as well as contexts, tags and extra data: - -- Event IDs are limited to 36 characters and must be valid UUIDs. -- Flag keys are limited to 32 characters. -- Flag values are limited to 200 characters. -- Tag keys are limited to 200 characters. -- Tag values are limited to 200 characters. -- Culprits are limited to 200 characters. -- Context objects are limited to 8kB. -- Individual extra data items are limited to 16kB. Total extra data is limited to 256kb. -- Messages are limited to 8192 characters. -- HTTP data (the body) is limited to 8kB. Always trim HTTP data before attaching it to the event. -- Stack traces are limited to 50 frames. If more are sent, data will be removed from the middle of the stack. -- Input messages in AI integrations recorded in the span attribute `gen_ai.request.messages` are limited to 20kB per span. Messages are trimmed and truncated if they exceed the limit, retaining the most recent messages. - -Additionally, size limits apply to all store requests for the total size of the request, event payload, and attachments. Sentry rejects all requests exceeding these limits. Please refer the following resources for the exact size limits: - -- Envelope Endpoint Size Limits diff --git a/develop-docs/sdk/foundations/transport/event-payloads/index.mdx b/develop-docs/sdk/foundations/transport/event-payloads/index.mdx index 9a3b94f531251..ab4f1628fb756 100644 --- a/develop-docs/sdk/foundations/transport/event-payloads/index.mdx +++ b/develop-docs/sdk/foundations/transport/event-payloads/index.mdx @@ -287,6 +287,23 @@ Fingerprints](https://docs.sentry.io/data-management/event-grouping/). Event ingestion imposes limits on the size of events. See [Envelope Size Limits](/sdk/foundations/transport/envelopes/#size-limits) for further details. +### Variable Size + +Fields in the event payload that allow user-specified or dynamic values are restricted in size. This applies to most meta data fields, such as variables in a stack trace, as well as contexts, tags and extra data: + +- Event IDs are limited to 36 characters and must be valid UUIDs. +- Flag keys are limited to 32 characters. +- Flag values are limited to 200 characters. +- Tag keys are limited to 200 characters. +- Tag values are limited to 200 characters. +- Culprits are limited to 200 characters. +- Context objects are limited to 8kB. +- Individual extra data items are limited to 16kB. Total extra data is limited to 256kb. +- Messages are limited to 8192 characters. +- HTTP data (the body) is limited to 8kB. Always trim HTTP data before attaching it to the event. +- Stack traces are limited to 50 frames. If more are sent, data will be removed from the middle of the stack. +- Input messages in AI integrations recorded in the span attribute `gen_ai.request.messages` are limited to 20kB per span. Messages are trimmed and truncated if they exceed the limit, retaining the most recent messages. + ## Core Interfaces All values in the event payload that are not basic attributes are data From ccf4982edba48aaebbfb7ef884f1a7fd61ad0a0c Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 16:29:21 +0100 Subject: [PATCH 02/12] docs(sdk): Move breadcrumb structuring to breadcrumbs interface Move the breadcrumb URL formatting and data scrubbing guidance from expected-features/data-handling to the Breadcrumbs Interface page where it belongs alongside the breadcrumb type definitions. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- .../sdk/expected-features/data-handling.mdx | 21 ------------------ .../transport/event-payloads/breadcrumbs.mdx | 22 +++++++++++++++++++ 2 files changed, 22 insertions(+), 21 deletions(-) diff --git a/develop-docs/sdk/expected-features/data-handling.mdx b/develop-docs/sdk/expected-features/data-handling.mdx index 6bde5c3a4464f..26d5a03d8d005 100644 --- a/develop-docs/sdk/expected-features/data-handling.mdx +++ b/develop-docs/sdk/expected-features/data-handling.mdx @@ -111,24 +111,3 @@ This helps Relay to know what kind of data it receives and this helps with scrub Additionally all semantic conventions of OpenTelemetry for database spans should be set in the `span.data` if applicable: https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/ - -### Breadcrumbs - -If the `message` in a breadcrumb contains an URL it should be formatted the same way as in `http` spans (see above). -If query strings are present in the URL or fragments (Browser SDKs only) are present in the URI, both should also be set in the data attribute like with `http` spans. - -```js -Sentry.addBreadcrumb({ - type: "http", - category: "xhr", - data: { - method: "POST", - url: "https://example.com/api/users/create.php", - "http.query": "username=ada&password=123&newsletter=0", - "http.fragment": "#foo", - }, -}); -``` - -Additionally all semantic conventions of OpenTelemetry for database spans should be set in the `data` if applicable: -https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/ diff --git a/develop-docs/sdk/foundations/transport/event-payloads/breadcrumbs.mdx b/develop-docs/sdk/foundations/transport/event-payloads/breadcrumbs.mdx index 8860d30021115..97408ff1ce420 100644 --- a/develop-docs/sdk/foundations/transport/event-payloads/breadcrumbs.mdx +++ b/develop-docs/sdk/foundations/transport/event-payloads/breadcrumbs.mdx @@ -291,3 +291,25 @@ _Internally, we display breadcrumbs of type `default` that contain category `ui. "timestamp": 1598613151.875368 } ``` + +## Structuring Data for Scrubbing + +For better data scrubbing on the server side, SDKs should save breadcrumb data in a structured way when possible. See [RFC-0038](https://github.com/getsentry/rfcs/blob/main/text/0038-scrubbing-sensitive-data.md) for background. + +If the `message` in a breadcrumb contains a URL, it should be formatted the same way as in `http` spans: `HTTP_METHOD scheme://host/path`. If query strings are present in the URL or fragments (Browser SDKs only) are present in the URI, both should be set in the `data` attribute rather than included in the URL. + +```js +Sentry.addBreadcrumb({ + type: "http", + category: "xhr", + data: { + method: "POST", + url: "https://example.com/api/users/create.php", + "http.query": "username=ada&password=123&newsletter=0", + "http.fragment": "#foo", + }, +}); +``` + +Additionally, all semantic conventions of OpenTelemetry for database spans should be set in the `data` if applicable: +https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/ From 095107c0e8ddbdafa526b0bc638ae3d133a64886 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 16:55:10 +0100 Subject: [PATCH 03/12] docs(sdk): Move lastEventId to scopes spec Move "Retrieve Last Event ID" from expected-features to the scopes spec. Added as a top-level Sentry.lastEventId() API under its own "Event ID Retrieval" heading, and as scope instance methods (set_last_event_id, last_event_id) noting isolation scope usage. The hub & scope spec already documents last_event_id() in its static API table. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 11 ----------- .../sdk/foundations/state-management/scopes/index.mdx | 8 ++++++++ 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 0b9da5b24637a..d42ba9593bc44 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -26,13 +26,6 @@ This behavior is typically provided by a default integration that can be disable Automatic addition of useful attributes such as `flags` or `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/expected-features/data-handling) for considerations. -## Rate Limiting - -Respect Sentry's HTTP 429 `Retry-After` header, or, if the SDK supports multiple payload types (e.g. errors and transactions), the `X-Sentry-Rate-Limits` header. Outgoing SDK requests should be dropped during the backoff period. - -See Rate Limiting for details. - - ## Backpressure Management Backend SDKs (typically used in server applications) should have backpressure management logic that dynamically downsamples transactions when the throughput in the system is too high. @@ -57,10 +50,6 @@ This functionality should be gated behind the `includeLocalVariables` option, wh Turn compiled or obfuscated code/method names in stack traces back into the original. Desymbolication always requires Sentry backend support. Not necessary for many languages. -## Retrieve Last Event ID - -Ability to get the ID of the last event sent. Event IDs are useful for correlation, logging, customers rolling their own feedback forms, etc. - ## List Loaded Libraries Include a list of loaded libraries (and versions) when sending an event. diff --git a/develop-docs/sdk/foundations/state-management/scopes/index.mdx b/develop-docs/sdk/foundations/state-management/scopes/index.mdx index aa4228d4af5b4..2949e80b5bf44 100644 --- a/develop-docs/sdk/foundations/state-management/scopes/index.mdx +++ b/develop-docs/sdk/foundations/state-management/scopes/index.mdx @@ -341,6 +341,12 @@ Capture functions operate on the **current scope**: | `Sentry.captureMessage(message)` | 1.0.0 | Capture a message on the current scope. | | `Sentry.captureEvent(event)` | 1.0.0 | Capture a raw event on the current scope. | +### Event ID Retrieval + +| Function | Since | Description | +|---|---|---| +| `Sentry.lastEventId()` | 1.0.0 | Return the ID of the last event sent from the isolation scope. Useful for correlation, logging, and custom user feedback forms. | + ### Scope Data Methods These methods are available on any scope instance (see [Behavior: Scope Data Methods](#scope-data-methods) for requirements): @@ -354,6 +360,8 @@ These methods are available on any scope instance (see [Behavior: Scope Data Met | `set_level(level)` | 1.0.0 | Override event severity level. | | `set_fingerprint(fingerprint[])` | 1.0.0 | Set grouping fingerprint. | | `add_event_processor(fn)` | 1.0.0 | Register an event processor callback. | +| `set_last_event_id(id)` | 1.0.0 | Store the ID of the last event sent. Typically set on the isolation scope by the SDK after sending an event. | +| `last_event_id()` | 1.0.0 | Return the ID of the last event sent. Typically read from the isolation scope. | | `clear()` | 1.0.0 | Reset scope to defaults, keeping event processors. | --- From 9f724e2bd971d941b8df5f5223448efb61915c99 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:03:39 +0100 Subject: [PATCH 04/12] docs(sdk): Remove backpressure management from expected-features The entry was just a pointer to sdk/telemetry/traces/backpressure/ which already covers all the content. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index d42ba9593bc44..86560ca54f11d 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -26,12 +26,6 @@ This behavior is typically provided by a default integration that can be disable Automatic addition of useful attributes such as `flags` or `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/expected-features/data-handling) for considerations. -## Backpressure Management - -Backend SDKs (typically used in server applications) should have backpressure management logic that dynamically downsamples transactions when the throughput in the system is too high. - -See Backpressure Management for details. - ## In-App frames Stack parsing can tell which frames should be identified as part of the user's application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix. From 9248c05f85629b02ebd498c5d2723ab7680bfd88 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:10:09 +0100 Subject: [PATCH 05/12] docs(sdk): Add modules integration spec, move from expected-features Create a new spec page for the Modules integration that attaches loaded library names and versions to events. Documents event enrichment behavior, platform-specific module sources, and caching. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 4 - .../foundations/client/integrations/index.mdx | 1 + .../client/integrations/modules.mdx | 107 ++++++++++++++++++ 3 files changed, 108 insertions(+), 4 deletions(-) create mode 100644 develop-docs/sdk/foundations/client/integrations/modules.mdx diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 86560ca54f11d..85235e5a22145 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -44,10 +44,6 @@ This functionality should be gated behind the `includeLocalVariables` option, wh Turn compiled or obfuscated code/method names in stack traces back into the original. Desymbolication always requires Sentry backend support. Not necessary for many languages. -## List Loaded Libraries - -Include a list of loaded libraries (and versions) when sending an event. - ## Buffer to Disk This feature is also known as 'Offline Caching'. diff --git a/develop-docs/sdk/foundations/client/integrations/index.mdx b/develop-docs/sdk/foundations/client/integrations/index.mdx index d3c6bf0717fa2..76ed6ee94c313 100644 --- a/develop-docs/sdk/foundations/client/integrations/index.mdx +++ b/develop-docs/sdk/foundations/client/integrations/index.mdx @@ -29,6 +29,7 @@ Related specs: - [HTTP Client Integration](/sdk/foundations/client/integrations/http-client) — HTTP client instrumentation guidelines - [GraphQL Integration](/sdk/foundations/client/integrations/graphql) — GraphQL client instrumentation guidelines - [Feature Flags Integration](/sdk/foundations/client/integrations/feature-flags) — feature flag tracking guidelines +- [Modules Integration](/sdk/foundations/client/integrations/modules) — loaded library and version reporting --- diff --git a/develop-docs/sdk/foundations/client/integrations/modules.mdx b/develop-docs/sdk/foundations/client/integrations/modules.mdx new file mode 100644 index 0000000000000..e81733ba7196e --- /dev/null +++ b/develop-docs/sdk/foundations/client/integrations/modules.mdx @@ -0,0 +1,107 @@ +--- +title: Modules +description: Integration for attaching loaded libraries and their versions to events, populating the event modules field. +spec_id: sdk/foundations/client/integrations/modules +spec_version: 1.0.0 +spec_status: stable +spec_depends_on: + - id: sdk/foundations/client/integrations + version: ">=1.0.0" +spec_changelog: + - version: 1.0.0 + date: 2026-03-04 + summary: Initial spec, extracted from expected features +sidebar_order: 4 +--- + + + + + +## Overview + +The Modules integration attaches a list of loaded libraries (packages, modules) and their versions to events. This populates the [`modules` field](/sdk/foundations/transport/event-payloads/#optional-attributes) on the event payload, which Sentry displays in the event detail view to help users identify dependency-related issues. + +This integration **SHOULD** be a default integration. + +--- + +## Behavior + + + +### Event Enrichment + +The integration **MUST** use the `processEvent` lifecycle hook to attach module information to events. + +The integration **MUST** populate `event.modules` as a map of module name to version string: + +```json +{ + "modules": { + "flask": "2.3.1", + "requests": "2.31.0", + "sqlalchemy": "2.0.19" + } +} +``` + +The integration **SHOULD** cache the module list, since installed packages rarely change during a process lifetime. + + + + + +### Module Sources + +How modules are discovered is platform-specific. SDKs **SHOULD** use the most reliable mechanism available on their platform. Common strategies include: + +- **Package manager metadata** — reading installed package registries (e.g., `pkg_resources` or `importlib.metadata` in Python, `package.json` dependencies in Node.js) +- **Runtime module cache** — inspecting loaded modules from the runtime (e.g., `require.cache` in Node.js CJS) +- **Build-time injection** — embedding module information at build time when runtime discovery is unavailable or incomplete (e.g., bundled environments) + +SDKs **MAY** combine multiple sources to produce the most complete list. When the same module appears in multiple sources, the more specific version (e.g., from a lockfile or runtime cache) **SHOULD** take precedence. + + + + + +### Event Type Filtering + +SDKs **MAY** skip attaching modules to certain event types (e.g., transactions) where the information is less useful, to reduce payload size. + + + +--- + +## Examples + +### JavaScript (Node.js) + +```javascript +// modulesIntegration is a default integration in @sentry/node +Sentry.init({ + dsn: "https://examplePublicKey@o0.ingest.sentry.io/0", +}); + +// Modules are automatically attached to error events. +// The integration reads from package.json and require.cache (CJS). +``` + +### Python + +```python +import sentry_sdk + +# ModulesIntegration is a default integration +sentry_sdk.init(dsn="https://examplePublicKey@o0.ingest.sentry.io/0") + +# Modules are automatically attached to error events. +# The integration reads from importlib.metadata / pkg_resources. +``` + +--- + +## Changelog + + From 0030e24f6f8afac75600308ec5baafb02ea72dec Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:20:03 +0100 Subject: [PATCH 06/12] docs(sdk): Move buffer-to-disk to transport/offline-caching Move the "Buffer to Disk" section and "Dealing With Network Failures" from expected-features to a new transport/offline-caching page. Tightened wording to use RFC 2119 keywords and promoted HTTP status code subsections to proper headings. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 51 --------------- .../sdk/foundations/transport/index.mdx | 2 +- .../foundations/transport/offline-caching.mdx | 65 +++++++++++++++++++ 3 files changed, 66 insertions(+), 52 deletions(-) create mode 100644 develop-docs/sdk/foundations/transport/offline-caching.mdx diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 85235e5a22145..f1116b70d110a 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -44,57 +44,6 @@ This functionality should be gated behind the `includeLocalVariables` option, wh Turn compiled or obfuscated code/method names in stack traces back into the original. Desymbolication always requires Sentry backend support. Not necessary for many languages. -## Buffer to Disk - -This feature is also known as 'Offline Caching'. - -Write events to disk before attempting to send, so that they can be retried in the event of a temporary network failure. Needs to implement a cap on the number of stored events. This is mostly useful on mobile and desktop(e.g: laptop) apps, where stable connectivity is often not available. - -### Dealing With Network Failures - -When SDKs receive an `HTTP 2xx` status code response from Sentry, they **MUST** consider it as a successful send. - -If Sentry returns an `HTTP 4xx` or `HTTP 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports/#network-failure-recording) as specified in the client reports spec. - -For an [`HTTP 413 Content Too Large`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) response, SDKs: - -* **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports/#network-failure-recording). -* **MUST NOT** retry sending the envelope. -* **SHOULD** log an error, informing users that the envelope was discarded due to size limits. -* **MAY** add information from the response body to the logged error. If doing so, SDKs **MUST** be aware that Relay can change or remove information in the response body for an `HTTP 413` at any time without notice. - -For an [`HTTP 429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response, SDKs: - -- **MUST** respect the [rate limiting rules](/sdk/expected-features/rate-limiting/), such as correctly parsing the retry-header. -- **MUST** discard the envelope, but **MUST NOT** record a [client report](/sdk/telemetry/client-reports/#network-failure-recording), because the upstream already does this. -- **MUST NOT** retry sending the envelope. - -SDKs **MAY** retry sending the envelope when a network error occurs, such as: - -* Connection timeout -* DSN resolution failure -* Connection reset by peer - -When other failures occur, like those caused by processing the file in the SDK itself, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports/#network-failure-recording) with the discard reason `internal_sdk_error`. Otherwise, the SDK might end up in an endless retry loop. - -See the [Client Reports — Network Failure Recording](/sdk/telemetry/client-reports/#network-failure-recording) spec for the full set of client report recording requirements for each HTTP status code. - - -#### Additional capabilities - -Consider having the SDK retry sending events once the device is back online, when such notification exists in the platform. - -Once the device is back online, the SDK is likely going to empty its disk queue in a quick burst of requests. This can trigger different abuse filters in Sentry. To account for that, it's considered to add a small delay between cached event captures. A recommended value is 100 milliseconds. - -If the SDK is being [rate-limited](/sdk/expected-features/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, consider stop consuming the disk cache until the `Retry-After` timeout is reached or the app restarts. - -#### Example implementations - -- [C#](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/Internal/Http/CachingTransport.cs) -- [Java](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/cache/EnvelopeCache.java) -- [Objective-C](https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentryHttpTransport.m) -- [TypeScript](https://github.com/getsentry/sentry-electron/blob/master/src/main/transports/electron-offline-net.ts) - ## Start-Up Crash Detection We recommend implementing this feature for mobile and desktop SDKs. diff --git a/develop-docs/sdk/foundations/transport/index.mdx b/develop-docs/sdk/foundations/transport/index.mdx index a284f6ada3e7a..590a687337093 100644 --- a/develop-docs/sdk/foundations/transport/index.mdx +++ b/develop-docs/sdk/foundations/transport/index.mdx @@ -4,7 +4,7 @@ description: How SDKs send data to Sentry - envelope format, authentication, com sidebar_order: 20 --- -The transport layer handles all communication between an SDK and the Sentry server. SDKs serialize data into [envelopes](envelopes/), [authenticate](authentication/) requests using DSN-derived credentials, optionally [compress](compression/) payloads, and respect [rate limits](rate-limiting/) communicated via response headers. +The transport layer handles all communication between an SDK and the Sentry server. SDKs serialize data into [envelopes](envelopes/), [authenticate](authentication/) requests using DSN-derived credentials, optionally [compress](compression/) payloads, respect [rate limits](rate-limiting/) communicated via response headers, and optionally [buffer envelopes to disk](offline-caching/) for retry on network failure. ## Reading the Response diff --git a/develop-docs/sdk/foundations/transport/offline-caching.mdx b/develop-docs/sdk/foundations/transport/offline-caching.mdx new file mode 100644 index 0000000000000..94e062ddf6d4e --- /dev/null +++ b/develop-docs/sdk/foundations/transport/offline-caching.mdx @@ -0,0 +1,65 @@ +--- +title: Offline Caching +description: How SDKs buffer envelopes to disk for retry when network connectivity is unavailable, and how to handle network failure responses. +sidebar_order: 5 +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined + in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement + levels. + + +## Overview + +Also known as "Buffer to Disk". SDKs write envelopes to disk before attempting to send, so that they can be retried in the event of a temporary network failure. SDKs **MUST** implement a cap on the number of stored envelopes. This feature is mostly useful on mobile and desktop apps, where stable connectivity is often not available. + +## Dealing With Network Failures + +When SDKs receive an `HTTP 2xx` status code response from Sentry, they **MUST** consider it as a successful send. + +If Sentry returns an `HTTP 4xx` or `HTTP 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports/#network-failure-recording) as specified in the client reports spec. + +### HTTP 413 Content Too Large + +For an [`HTTP 413 Content Too Large`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) response, SDKs: + +* **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports/#network-failure-recording). +* **MUST NOT** retry sending the envelope. +* **SHOULD** log an error, informing users that the envelope was discarded due to size limits. +* **MAY** add information from the response body to the logged error. If doing so, SDKs **MUST** be aware that Relay can change or remove information in the response body for an `HTTP 413` at any time without notice. + +### HTTP 429 Too Many Requests + +For an [`HTTP 429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response, SDKs: + +- **MUST** respect the [rate limiting rules](/sdk/expected-features/rate-limiting/), such as correctly parsing the retry-header. +- **MUST** discard the envelope, but **MUST NOT** record a [client report](/sdk/telemetry/client-reports/#network-failure-recording), because the upstream already does this. +- **MUST NOT** retry sending the envelope. + +### Network Errors + +SDKs **MAY** retry sending the envelope when a network error occurs, such as: + +* Connection timeout +* DSN resolution failure +* Connection reset by peer + +When other failures occur, like those caused by processing the file in the SDK itself, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports/#network-failure-recording) with the discard reason `internal_sdk_error`. Otherwise, the SDK might end up in an endless retry loop. + +See the [Client Reports — Network Failure Recording](/sdk/telemetry/client-reports/#network-failure-recording) spec for the full set of client report recording requirements for each HTTP status code. + +## Additional Capabilities + +SDKs **SHOULD** retry sending envelopes once the device is back online, when such notification exists in the platform. + +Once the device is back online, the SDK is likely going to empty its disk queue in a quick burst of requests. This can trigger abuse filters in Sentry. To account for that, SDKs **SHOULD** add a small delay between cached envelope sends. A recommended value is 100 milliseconds. + +If the SDK is being [rate-limited](/sdk/expected-features/rate-limiting/), which causes the SDK to drop any envelope that reaches its HTTP transport, SDKs **SHOULD** stop consuming the disk cache until the `Retry-After` timeout is reached or the app restarts. + +## Example Implementations + +- [C#](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/Internal/Http/CachingTransport.cs) +- [Java](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/cache/EnvelopeCache.java) +- [Objective-C](https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentryHttpTransport.m) +- [TypeScript](https://github.com/getsentry/sentry-electron/blob/master/src/main/transports/electron-offline-net.ts) From 7fb14c581147cceb715f7af5df11c05409962ee5 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:22:09 +0100 Subject: [PATCH 07/12] docs(sdk): Move background sending to transport spec Move "Background Sending" from expected-features to the transport index page with RFC 2119 keywords. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 7 ------- develop-docs/sdk/foundations/transport/index.mdx | 4 ++++ 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index f1116b70d110a..1391090691336 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -9,13 +9,6 @@ sidebar_order: 5 including the Scopes and Client specs. -## Background Sending - -Events should be transmitted in a background thread or similar system. This queue must be flushed when the -application shuts down with a specific timeout. This feature is typically user facing and explained -as part of [shutdown and draining](https://docs.sentry.io/platforms/javascript/configuration/draining/). - - ## Uncaught Exception Handler Ability for the SDK to be set as a hook to record any uncaught exceptions. At the language level this is typically a global hook provided by the language itself. For framework integrations this might be part of middleware or some other system. diff --git a/develop-docs/sdk/foundations/transport/index.mdx b/develop-docs/sdk/foundations/transport/index.mdx index 590a687337093..a28f21f1e3c14 100644 --- a/develop-docs/sdk/foundations/transport/index.mdx +++ b/develop-docs/sdk/foundations/transport/index.mdx @@ -6,6 +6,10 @@ sidebar_order: 20 The transport layer handles all communication between an SDK and the Sentry server. SDKs serialize data into [envelopes](envelopes/), [authenticate](authentication/) requests using DSN-derived credentials, optionally [compress](compression/) payloads, respect [rate limits](rate-limiting/) communicated via response headers, and optionally [buffer envelopes to disk](offline-caching/) for retry on network failure. +## Background Sending + +Envelopes **SHOULD** be transmitted in a background thread or equivalent asynchronous mechanism so that sending does not block the application. The send queue **MUST** be flushed when the application shuts down, with a configurable timeout. This is typically exposed to users as [shutdown and draining](https://docs.sentry.io/platforms/javascript/configuration/draining/). + ## Reading the Response On success, you will receive an HTTP response from the server containing a JSON payload with information on the submitted payload: From 0dc8565f030f74153ce0bd10aa802978f1203dde Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:28:30 +0100 Subject: [PATCH 08/12] docs(sdk): Move log context to client configuration spec Move "Log context" (contextTags / MDC) from expected-features to the configuration spec as a SpecSection and client options table entry. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 6 ------ .../foundations/client/configuration/index.mdx | 17 +++++++++++++++++ 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 1391090691336..ca5d96084bed6 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -89,9 +89,3 @@ SDK controls what is an actual size in bytes for each option: - `small` - `1000` bytes - `medium` - `10000` bytes (default) - `always` - -## Log context - -Some logging frameworks provide an option to set logging context. In Java this is called MDC (Mapped Diagnostic Context). - -Users should be able to set a list of logging context entries in a configuration option `contextTags` to tell the SDK to convert the entries to Sentry tags. diff --git a/develop-docs/sdk/foundations/client/configuration/index.mdx b/develop-docs/sdk/foundations/client/configuration/index.mdx index d1dc8d1b6acab..01153b888dac0 100644 --- a/develop-docs/sdk/foundations/client/configuration/index.mdx +++ b/develop-docs/sdk/foundations/client/configuration/index.mdx @@ -53,6 +53,7 @@ Core options that all SDKs **MUST** or **SHOULD** support: | `traces_sample_rate` | `float [0,1]` | Trace/transaction sample rate. | | `traces_sampler` | `callback` | Dynamic per-transaction sample rate. | | `trace_propagation_targets` | `array` | URL patterns for outgoing trace header injection. | +| `context_tags` | `array` | List of logging context keys to convert to Sentry tags. See [Log Context](#log-context). | @@ -176,6 +177,22 @@ ignore_transactions = ['GET /api/health','/api/v1/*'] + + +### Log Context + +Some logging frameworks provide an option to set logging context. In Java this is called MDC (Mapped Diagnostic Context). + +SDKs that integrate with platform logging frameworks **SHOULD** support a `context_tags` configuration option. This option accepts a list of logging context keys whose values the SDK converts to Sentry tags on captured events. + +```python +sentry_sdk.init( + context_tags=["request_id", "tenant"], +) +``` + + + --- ## Changelog From cb7d427293b257930af21a0805dea35aea086fb4 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:30:05 +0100 Subject: [PATCH 09/12] docs(sdk): Move request body size to client configuration spec Move "Attaching Request Body in Server SDKs" from expected-features to the configuration spec as a SpecSection and client options table entry (max_request_body_size). Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 12 ------------ .../foundations/client/configuration/index.mdx | 16 ++++++++++++++++ 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index ca5d96084bed6..115fb9e60ed8a 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -77,15 +77,3 @@ ones. We can always add these values later. ## HTTP Proxy Ability to use an HTTP proxy. Often easy to implement using the existing HTTP client. This should be picked up from the system config if possible or explicit config in the client options. - -## Attaching Request Body in Server SDKs - -Ability for the SDK to attach request body to events and triggered during the execution of request. - -User should be able to set a configuration option `maxRequestBodySize` to instruct SDK how big requests bodies should be attached. -SDK controls what is an actual size in bytes for each option: - -- `none` -- `small` - `1000` bytes -- `medium` - `10000` bytes (default) -- `always` diff --git a/develop-docs/sdk/foundations/client/configuration/index.mdx b/develop-docs/sdk/foundations/client/configuration/index.mdx index 01153b888dac0..b8ceed777ac61 100644 --- a/develop-docs/sdk/foundations/client/configuration/index.mdx +++ b/develop-docs/sdk/foundations/client/configuration/index.mdx @@ -54,6 +54,7 @@ Core options that all SDKs **MUST** or **SHOULD** support: | `traces_sampler` | `callback` | Dynamic per-transaction sample rate. | | `trace_propagation_targets` | `array` | URL patterns for outgoing trace header injection. | | `context_tags` | `array` | List of logging context keys to convert to Sentry tags. See [Log Context](#log-context). | +| `max_request_body_size` | `string` | Controls how large request bodies may be before the SDK skips attaching them. Server SDKs only. See [Request Body Size](#request-body-size). | @@ -177,6 +178,21 @@ ignore_transactions = ['GET /api/health','/api/v1/*'] + + +### Request Body Size + +Server SDKs **SHOULD** support attaching the incoming HTTP request body to events. The `max_request_body_size` option controls the maximum body size the SDK will attach. The SDK defines the actual byte thresholds for each setting: + +| Value | Max Size | +|---|---| +| `none` | Never attach the body | +| `small` | 1,000 bytes | +| `medium` | 10,000 bytes (default) | +| `always` | No limit | + + + ### Log Context From 9c8b3f2669781ffbdbfd914ca276afa1fc92ccdf Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:32:22 +0100 Subject: [PATCH 10/12] docs(sdk): Move automatic context data to state management specs Add "Automatic Context Data" concept to both the scopes spec and the hub & scope spec, explaining that SDKs and integrations auto-populate scopes with contextual data via framework hooks. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 4 ---- .../sdk/foundations/state-management/hub-and-scope/index.mdx | 2 ++ .../sdk/foundations/state-management/scopes/index.mdx | 4 ++++ 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 115fb9e60ed8a..a78b62e4456db 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -15,10 +15,6 @@ Ability for the SDK to be set as a hook to record any uncaught exceptions. At th This behavior is typically provided by a default integration that can be disabled. -## Automatic Context Data - -Automatic addition of useful attributes such as `flags` or `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/expected-features/data-handling) for considerations. - ## In-App frames Stack parsing can tell which frames should be identified as part of the user's application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix. diff --git a/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx b/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx index 0e2a56ef30874..5aeda29ef0413 100644 --- a/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx +++ b/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx @@ -61,6 +61,8 @@ The decision to remove the Hub from all Sentry SDKs was confirmed on 2024-05-03 - **Disabled SDK**: The SDK is considered disabled when the client has no transport. In this state, callbacks like `configure_scope` and event processors **SHOULD NOT** be invoked, and breadcrumbs **SHOULD NOT** be recorded. +- **Automatic Context Data**: SDKs and their integrations automatically populate scopes with useful contextual data such as tags, contexts, and extras. This typically happens by hooking into a framework (e.g., a web framework middleware setting request-related context on the scope). See [Data Handling](/sdk/expected-features/data-handling) for considerations around sensitive data. + --- ## Behavior diff --git a/develop-docs/sdk/foundations/state-management/scopes/index.mdx b/develop-docs/sdk/foundations/state-management/scopes/index.mdx index 2949e80b5bf44..5bdadf1bebbc9 100644 --- a/develop-docs/sdk/foundations/state-management/scopes/index.mdx +++ b/develop-docs/sdk/foundations/state-management/scopes/index.mdx @@ -94,6 +94,10 @@ When a scope is forked, the new scope receives a copy of all data from the paren This replaces the manual hub-cloning pattern from the old model. Users no longer need to manage scope isolation — it happens automatically when spans are created or `withScope()` is called. +### Automatic Context Data + +SDKs and their integrations automatically populate scopes with useful contextual data such as tags, contexts, and attributes. This typically happens by hooking into a framework (e.g., a web framework middleware setting request-related context on the isolation scope). This automatic enrichment is a key benefit of scopes — users get useful data on events without manual instrumentation. See [Data Handling](/sdk/expected-features/data-handling) for considerations around sensitive data. + ### Scope Chain Clients are resolved by walking the scope chain: current scope -> isolation scope -> global scope. If no client is found, a NoOpClient is used (see [Client Resolution](#client-resolution)). From b08ebb8b78218ca6415a400d7cc88c398f967779 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:39:33 +0100 Subject: [PATCH 11/12] docs(sdk): Move HTTP proxy to transport spec Move "HTTP Proxy" from expected-features to the transport index page. Documents proxy option, environment variable precedence (proxy, https_proxy, http_proxy, no_proxy), and optional auth/CA support based on the sentry-javascript implementation. Part of the effort to retire sdk/expected-features/. Co-Authored-By: Claude --- develop-docs/sdk/expected-features/index.mdx | 4 ---- develop-docs/sdk/foundations/transport/index.mdx | 15 +++++++++++++++ 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index a78b62e4456db..dc5ea0e02f248 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -69,7 +69,3 @@ ones. We can always add these values later. #### Example implementations - [Java](https://github.com/getsentry/sentry-java/pull/2277) - [Objective-C](https://github.com/getsentry/sentry-cocoa/pull/2220) - -## HTTP Proxy - -Ability to use an HTTP proxy. Often easy to implement using the existing HTTP client. This should be picked up from the system config if possible or explicit config in the client options. diff --git a/develop-docs/sdk/foundations/transport/index.mdx b/develop-docs/sdk/foundations/transport/index.mdx index a28f21f1e3c14..a95939e0b52dd 100644 --- a/develop-docs/sdk/foundations/transport/index.mdx +++ b/develop-docs/sdk/foundations/transport/index.mdx @@ -10,6 +10,21 @@ The transport layer handles all communication between an SDK and the Sentry serv Envelopes **SHOULD** be transmitted in a background thread or equivalent asynchronous mechanism so that sending does not block the application. The send queue **MUST** be flushed when the application shuts down, with a configurable timeout. This is typically exposed to users as [shutdown and draining](https://docs.sentry.io/platforms/javascript/configuration/draining/). +## HTTP Proxy + +SDKs **SHOULD** support routing requests through an HTTP proxy. The proxy **SHOULD** be configurable via a `proxy` option in `Sentry.init()` and **SHOULD** also be picked up from the system environment when not explicitly configured. + +SDKs **SHOULD** respect the following environment variables, in order of precedence: + +1. `options.proxy` — explicit SDK configuration (highest priority) +2. `https_proxy` — for HTTPS requests to Sentry +3. `http_proxy` — fallback for all requests +4. `no_proxy` — comma-separated list of hostnames that bypass the proxy + +When a proxy is configured, the SDK **MUST** use it for all outgoing requests to Sentry. When `no_proxy` matches the Sentry hostname, the proxy **MUST** be bypassed. + +SDKs **MAY** support proxy authentication (username/password) and custom CA certificates for secure proxy connections. + ## Reading the Response On success, you will receive an HTTP response from the server containing a JSON payload with information on the submitted payload: From 5edbc85a26292cd3d0812468181c9025ac595fd4 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Wed, 4 Mar 2026 17:43:18 +0100 Subject: [PATCH 12/12] fix(sdk): Update broken links from expected-features migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - #retrieve-last-event-id → scopes/#event-id-retrieval - #dealing-with-network-failures → transport/offline-caching/ - #variable-size → transport/event-payloads/#variable-size Co-Authored-By: Claude --- .../sdk/foundations/processing/telemetry-processor/index.mdx | 2 +- develop-docs/sdk/telemetry/feedbacks.mdx | 2 +- docs/concepts/data-management/size-limits.mdx | 2 +- docs/platforms/python/configuration/options.mdx | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx index 875063216d3c9..a19dbc3762067 100644 --- a/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx +++ b/develop-docs/sdk/foundations/processing/telemetry-processor/index.mdx @@ -154,7 +154,7 @@ Here are the common requirements for all platforms: 2. The telemetry scheduler **SHOULD** attach the client reports to the envelopes it forwards to the transport. 3. When the telemetry queue overflows and drops envelopes, it **MUST** record the client report. -To be defined: How exactly does the telemetry scheduler interact with the transport to correctly remove items from the telemetry queue based on the received HTTP info and how to adhere to the [dealing with network failure](/sdk/expected-features/#dealing-with-network-failures) requirements. +To be defined: How exactly does the telemetry scheduler interact with the transport to correctly remove items from the telemetry queue based on the received HTTP info and how to adhere to the [dealing with network failure](/sdk/foundations/transport/offline-caching/#dealing-with-network-failures) requirements. ## Client Reports diff --git a/develop-docs/sdk/telemetry/feedbacks.mdx b/develop-docs/sdk/telemetry/feedbacks.mdx index 8832cde1044ad..66f28290c2e1f 100644 --- a/develop-docs/sdk/telemetry/feedbacks.mdx +++ b/develop-docs/sdk/telemetry/feedbacks.mdx @@ -111,7 +111,7 @@ On mobile and desktop, it is common to prompt the user for feedback after a cras ### Backend Platforms -On backend platforms, SDKs **SHOULD** document how to use the [last event ID](/sdk/expected-features/#retrieve-last-event-id) to prompt the user for feedback themselves. +On backend platforms, SDKs **SHOULD** document how to use the [last event ID](/sdk/foundations/state-management/scopes/#event-id-retrieval) to prompt the user for feedback themselves. diff --git a/docs/concepts/data-management/size-limits.mdx b/docs/concepts/data-management/size-limits.mdx index ee9f173fcc580..104792e6eb208 100644 --- a/docs/concepts/data-management/size-limits.mdx +++ b/docs/concepts/data-management/size-limits.mdx @@ -27,4 +27,4 @@ Sentry's exact size limits may change over time. For more information, please re - [Envelope Size Limits](https://develop.sentry.dev/sdk/data-model/envelopes/#size-limits) - [Minidump Size Limits](/platforms/native/guides/minidumps/#size-limits) -- [Variable Size Limits](https://develop.sentry.dev/sdk/expected-features/data-handling/#variable-size) +- [Variable Size Limits](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/#variable-size) diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx index 9ed296b70b552..a378a736d04cf 100644 --- a/docs/platforms/python/configuration/options.mdx +++ b/docs/platforms/python/configuration/options.mdx @@ -174,7 +174,7 @@ This parameter controls whether integrations should capture HTTP request bodies. - `medium`: Medium and small requests will be captured (typically 10KB). - `always`: The SDK will always capture the request body as long as Sentry can make sense of it. -Please note that the Sentry server [limits HTTP request body size](https://develop.sentry.dev/sdk/expected-features/data-handling/#variable-size). The server always enforces its size limit, regardless of how you configure this option. +Please note that the Sentry server [limits HTTP request body size](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/#variable-size). The server always enforces its size limit, regardless of how you configure this option. @@ -380,7 +380,7 @@ If `trace_propagation_targets` is not provided, trace data is attached to every -If set to `True`, the SDK will only continue a trace if the `org_id` of the incoming trace found in the +If set to `True`, the SDK will only continue a trace if the `org_id` of the incoming trace found in the `baggage` header matches the `org_id` of the current Sentry client and only if BOTH are present. If set to `False`, consistency of `org_id` will only be enforced if both are present. If either are missing, the trace will be continued.