Skip to content

Commit b329b65

Browse files
authored
feat(develop): Add clarification for capturing internal exceptions in SDKs (#13032)
1 parent baffd0b commit b329b65

File tree

1 file changed

+16
-0
lines changed

1 file changed

+16
-0
lines changed

develop-docs/sdk/overview.mdx

+16
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,8 @@ happens immediately that may result in a different response code (and message).
294294

295295
## Handling Errors
296296

297+
### Server Errors
298+
297299
We **highly encourage** that your SDK handle failures from the Sentry server
298300
gracefully. Specifically, SDKs must honor the `429` status code and not attempt
299301
sending until the `Retry-After` kicks in. SDKs should drop events if Sentry is
@@ -328,6 +330,20 @@ Retrying too often may cause further rate limiting or blocking by the Sentry
328330
server.
329331
</Alert>
330332

333+
### SDK Errors
334+
335+
We try our best to make our SDKs error-free. We are an exception monitoring service after all
336+
and throwing our own exceptions is awkward. However, if our SDKs do throw exceptions, we have to make
337+
sure we swallow them gracefully and emit an error level log describing the failure.
338+
339+
As a **design principle**, we never capture Sentry events for exceptions happening within our SDKs, including within user-defined callbacks and hooks such as `before_send` or `traces_sampler`.
340+
341+
The reason we avoid capturing internal SDK exceptions is that we are already in an event capturing flow
342+
where the scope has been applied and capturing another event at that point in the lifecycle
343+
would lead to undefined behavior. In the worst case, we could create a busy loop of creating and sending events repeatedly until the system crashes.
344+
345+
In mobile SDKs, unhandled crashes will still make it to Sentry via the crash handlers. See [SDK Crash Detection](https://github.com/getsentry/sentry/tree/master/src/sentry/utils/sdk_crashes#sdk-crash-detection) for more details.
346+
331347
## Concurrency (Scope and Hubs)
332348

333349
SDKs are supposed to provide standardized concurrency handling through the

0 commit comments

Comments
 (0)