feat: Add exponential backoff and log deduplication to Spotlight (#5025)

* feat: Add exponential backoff and log deduplication to Spotlight transport

When the Spotlight server is unreachable, the SDK now logs the error
only once and implements exponential backoff (1s initial, 60s max)
before retrying, per the Spotlight error handling spec.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: James Crosswell <james.crosswell@gmail.com>

Author: 3 people

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features ✨
+
+- feat: Add exponential backoff and log deduplication to Spotlight transport by @mattico in [#5025](https://github.com/getsentry/sentry-dotnet/pull/5025)
+
 ## 6.6.0
 
 ### Features ✨

src/Sentry/Http/SpotlightHttpTransport.cs

@@ -12,6 +12,7 @@ internal class SpotlightHttpTransport : HttpTransport
     private readonly HttpClient _httpClient;
     private readonly Uri _spotlightUrl;
     private readonly ISystemClock _clock;
+    private readonly ExponentialBackoff _backoff;
 
     public SpotlightHttpTransport(ITransport inner, SentryOptions options, HttpClient httpClient, Uri spotlightUrl, ISystemClock clock)
         : base(options, httpClient)
@@ -21,6 +22,7 @@ public SpotlightHttpTransport(ITransport inner, SentryOptions options, HttpClien
         _spotlightUrl = spotlightUrl;
         _inner = inner;
         _clock = clock;
+        _backoff = new ExponentialBackoff(clock);
     }
 
     protected internal override HttpRequestMessage CreateRequest(Envelope envelope)
@@ -38,23 +40,79 @@ public override async Task SendEnvelopeAsync(Envelope envelope, CancellationToke
     {
         var sentryTask = _inner.SendEnvelopeAsync(envelope, cancellationToken);
 
-        try
+        if (_backoff.ShouldAttempt())
         {
-            // Send to spotlight
-            using var processedEnvelope = ProcessEnvelope(envelope);
-            if (processedEnvelope.Items.Count > 0)
+            try
             {
-                using var request = CreateRequest(processedEnvelope);
-                using var response = await _httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
-                await HandleResponseAsync(response, processedEnvelope, cancellationToken).ConfigureAwait(false);
+                // Send to spotlight
+                using var processedEnvelope = ProcessEnvelope(envelope);
+                if (processedEnvelope.Items.Count > 0)
+                {
+                    using var request = CreateRequest(processedEnvelope);
+                    using var response = await _httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
+                    await HandleResponseAsync(response, processedEnvelope, cancellationToken).ConfigureAwait(false);
+
+                    _backoff.RecordSuccess();
+                }
+            }
+            catch (Exception e)
+            {
+                int failureCount = _backoff.RecordFailure();
+                if (failureCount == 1)
+                {
+                    _options.LogError(e, "Failed sending envelope to Spotlight.");
+                }
             }
-        }
-        catch (Exception e)
-        {
-            _options.LogError(e, "Failed sending envelope to Spotlight.");
         }
 
         // await the Sentry request before returning
         await sentryTask.ConfigureAwait(false);
     }
+
+    private class ExponentialBackoff
+    {
+        private static readonly TimeSpan InitialRetryDelay = TimeSpan.FromSeconds(1);
+        private static readonly TimeSpan MaxRetryDelay = TimeSpan.FromSeconds(60);
+
+        private readonly ISystemClock _clock;
+
+        private readonly Lock _lock = new();
+        private TimeSpan _retryDelay = InitialRetryDelay;
+        private DateTimeOffset _retryAfter = DateTimeOffset.MinValue;
+        private int _failureCount;
+
+        public ExponentialBackoff(ISystemClock clock)
+        {
+            _clock = clock;
+        }
+
+        public bool ShouldAttempt()
+        {
+            lock (_lock)
+            {
+                return _clock.GetUtcNow() >= _retryAfter;
+            }
+        }
+
+        public int RecordFailure()
+        {
+            lock (_lock)
+            {
+                _failureCount++;
+                _retryAfter = _clock.GetUtcNow() + _retryDelay;
+                _retryDelay = TimeSpan.FromTicks(Math.Min(_retryDelay.Ticks * 2, MaxRetryDelay.Ticks));
+                return _failureCount;
+            }
+        }
+
+        public void RecordSuccess()
+        {
+            lock (_lock)
+            {
+                _failureCount = 0;
+                _retryDelay = InitialRetryDelay;
+                _retryAfter = DateTimeOffset.MinValue;
+            }
+        }
+    }
 }