From 11ff740c0c40d121f9d2f941be52a143422481c0 Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Fri, 25 Feb 2022 11:31:27 -0500 Subject: [PATCH 1/4] sdk offline caching considerations --- src/docs/sdk/features.mdx | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/features.mdx b/src/docs/sdk/features.mdx index f6b3d7fb5f..3c0b34d645 100644 --- a/src/docs/sdk/features.mdx +++ b/src/docs/sdk/features.mdx @@ -155,9 +155,28 @@ Include a list of loaded libraries (and versions) when sending an event. ## Buffer to Disk -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 feature is also known as 'Offline Caching'. -This is mostly useful on mobile clients where connectivity is often not available. +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. + +#### Deailing with failures + +It's important to note that retry is only considered in the event of a network failure. For example: + +* Connection timeout +* DSN resolution failure +* Connection reset by peer + +Other failures, like those caused by processing the file in the SDK itself, the payload should be discarded since those are likely to end up on an endless retry. +If the event reached Sentry and a HTTP response status code was received, even if in the event of a `500`, the event should be discarded. + +#### 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 latency between cached event captures. A recommended value is 100 milliseconds. + +If the SDK is being [rate-limited](/sdk/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, cosider stop consuming the disk cache until the backoff timeout is reached or the app restarts. ## HTTP Proxy From 413f721810c62d61f0ad2f12341845c5e0aa1e92 Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Fri, 25 Feb 2022 17:34:32 +0100 Subject: [PATCH 2/4] Apply suggestions from code review --- src/docs/sdk/features.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/features.mdx b/src/docs/sdk/features.mdx index 3c0b34d645..5322db5840 100644 --- a/src/docs/sdk/features.mdx +++ b/src/docs/sdk/features.mdx @@ -174,9 +174,9 @@ If the event reached Sentry and a HTTP response status code was received, even i 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 latency between cached event captures. A recommended value is 100 milliseconds. +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/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, cosider stop consuming the disk cache until the backoff timeout is reached or the app restarts. +If the SDK is being [rate-limited](/sdk/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, cosider stop consuming the disk cache until the `Retry-After` timeout is reached or the app restarts. ## HTTP Proxy From a6d3a5f649e85ba6c9f4e464e9329d6767f8e0e0 Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Sat, 26 Feb 2022 00:54:05 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Abhijeet Prasad --- src/docs/sdk/features.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/sdk/features.mdx b/src/docs/sdk/features.mdx index 5322db5840..803a6d3778 100644 --- a/src/docs/sdk/features.mdx +++ b/src/docs/sdk/features.mdx @@ -159,7 +159,7 @@ 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. -#### Deailing with failures +#### Dealing with failures It's important to note that retry is only considered in the event of a network failure. For example: @@ -168,7 +168,7 @@ It's important to note that retry is only considered in the event of a network f * Connection reset by peer Other failures, like those caused by processing the file in the SDK itself, the payload should be discarded since those are likely to end up on an endless retry. -If the event reached Sentry and a HTTP response status code was received, even if in the event of a `500`, the event should be discarded. +If the event reached Sentry and a HTTP response status code was received, even in the event of a `500` response, the event should be discarded. #### Additional capabilities From 078ab2f0298f9b114ea1219f933325141c8d3d7a Mon Sep 17 00:00:00 2001 From: Bruno Garcia Date: Sat, 26 Feb 2022 01:00:20 +0100 Subject: [PATCH 4/4] Update src/docs/sdk/features.mdx --- src/docs/sdk/features.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/docs/sdk/features.mdx b/src/docs/sdk/features.mdx index 803a6d3778..4af36bf1eb 100644 --- a/src/docs/sdk/features.mdx +++ b/src/docs/sdk/features.mdx @@ -178,6 +178,13 @@ Once the device is back online, the SDK is likely going to empty its disk queue If the SDK is being [rate-limited](/sdk/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, cosider 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) + ## 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.