From 01d43e54bcdebab22bf3254cdb6e482dee665179 Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Tue, 18 Mar 2025 16:00:44 +0100 Subject: [PATCH 1/5] feat(develop): Add clarification for capturing internal exceptions in SDKs --- develop-docs/sdk/overview.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/develop-docs/sdk/overview.mdx b/develop-docs/sdk/overview.mdx index b660f65ccf556..53e471dcca86f 100644 --- a/develop-docs/sdk/overview.mdx +++ b/develop-docs/sdk/overview.mdx @@ -294,6 +294,8 @@ happens immediately that may result in a different response code (and message). ## Handling Errors +### Server Errors + We **highly encourage** that your SDK handle failures from the Sentry server gracefully. Specifically, SDKs must honor the `429` status code and not attempt sending until the `Retry-After` kicks in. SDKs should drop events if Sentry is @@ -328,6 +330,19 @@ Retrying too often may cause further rate limiting or blocking by the Sentry server. +### SDK Errors + +We try our best to make our SDKs error-free. We are an exception monitoring service after all +and throwing our own exceptions is awkward. However, if our SDKs do throw exceptions, we have to make +sure we swallow them gracefully and emit an error level log describing the failure. + +As a **design principle**, we never capture Sentry events for exceptions happening within our SDKs. +This includes user-defined callbacks and hooks such as `before_send`, `traces_sampler` and so on. + +The main justification for this is that we are already in an event capturing flow where the scope has been applied +and capturing another event at that point in the lifecycle would lead to undefined behavior. In the worst case, +we could create a busy loop of creating and sending events repeatedly till the system crashes. + ## Concurrency (Scope and Hubs) SDKs are supposed to provide standardized concurrency handling through the From f294ede151a5ba3e79bca8d2c6e9b588cbf179d6 Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Tue, 18 Mar 2025 16:22:24 +0100 Subject: [PATCH 2/5] Update develop-docs/sdk/overview.mdx Co-authored-by: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/overview.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/develop-docs/sdk/overview.mdx b/develop-docs/sdk/overview.mdx index 53e471dcca86f..a680a17b9f575 100644 --- a/develop-docs/sdk/overview.mdx +++ b/develop-docs/sdk/overview.mdx @@ -336,8 +336,7 @@ We try our best to make our SDKs error-free. We are an exception monitoring serv and throwing our own exceptions is awkward. However, if our SDKs do throw exceptions, we have to make sure we swallow them gracefully and emit an error level log describing the failure. -As a **design principle**, we never capture Sentry events for exceptions happening within our SDKs. -This includes user-defined callbacks and hooks such as `before_send`, `traces_sampler` and so on. +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`. The main justification for this is that we are already in an event capturing flow where the scope has been applied and capturing another event at that point in the lifecycle would lead to undefined behavior. In the worst case, From e1921e168f6bcb5825a9526053e90960b216bf99 Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Tue, 18 Mar 2025 16:25:59 +0100 Subject: [PATCH 3/5] fix --- develop-docs/sdk/overview.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/overview.mdx b/develop-docs/sdk/overview.mdx index a680a17b9f575..7d57dafe7d525 100644 --- a/develop-docs/sdk/overview.mdx +++ b/develop-docs/sdk/overview.mdx @@ -338,9 +338,9 @@ sure we swallow them gracefully and emit an error level log describing the failu 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`. -The main justification for this is that we are already in an event capturing flow where the scope has been applied -and capturing another event at that point in the lifecycle would lead to undefined behavior. In the worst case, -we could create a busy loop of creating and sending events repeatedly till the system crashes. +The reason we avoid capturing internal SDK exceptions is that we are already in an event capturing flow +where the scope has been applied and capturing another event at that point in the lifecycle +would lead to undefined behavior. In the worst case, we could create a busy loop of creating and sending events repeatedly till the system crashes. ## Concurrency (Scope and Hubs) From 69d8ac2e917dd36dc73a32210d2c0a5018a5c5ee Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Tue, 18 Mar 2025 16:29:47 +0100 Subject: [PATCH 4/5] Update develop-docs/sdk/overview.mdx Co-authored-by: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- develop-docs/sdk/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/overview.mdx b/develop-docs/sdk/overview.mdx index 7d57dafe7d525..3c477e8c116d8 100644 --- a/develop-docs/sdk/overview.mdx +++ b/develop-docs/sdk/overview.mdx @@ -340,7 +340,7 @@ As a **design principle**, we never capture Sentry events for exceptions happeni The reason we avoid capturing internal SDK exceptions is that we are already in an event capturing flow where the scope has been applied and capturing another event at that point in the lifecycle -would lead to undefined behavior. In the worst case, we could create a busy loop of creating and sending events repeatedly till the system crashes. +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. ## Concurrency (Scope and Hubs) From d02f48d5bc3ea2e694c7325c025a3641c558c431 Mon Sep 17 00:00:00 2001 From: Neel Shah Date: Tue, 18 Mar 2025 16:52:31 +0100 Subject: [PATCH 5/5] Add crash detection info --- develop-docs/sdk/overview.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/develop-docs/sdk/overview.mdx b/develop-docs/sdk/overview.mdx index 3c477e8c116d8..eef8bf2c15727 100644 --- a/develop-docs/sdk/overview.mdx +++ b/develop-docs/sdk/overview.mdx @@ -342,6 +342,8 @@ The reason we avoid capturing internal SDK exceptions is that we are already in where the scope has been applied and capturing another event at that point in the lifecycle 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. +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. + ## Concurrency (Scope and Hubs) SDKs are supposed to provide standardized concurrency handling through the