fix(spotlight): align behavior with SDK spec

Align the Spotlight implementation with the official spec at
https://develop.sentry.dev/sdk/expected-features/spotlight/

Changes:

1. Fix precedence rules:
   - When spotlight=True and SENTRY_SPOTLIGHT env var is a URL, use the
     env var URL (per spec requirement)
   - Log warning when config URL overrides env var URL
   - Log warning when spotlight=False explicitly disables despite env
     var being set

2. Route all envelopes to Spotlight:
   - Sessions, logs, and metrics now also get sent to Spotlight via the
     _capture_envelope callback
   - Move Spotlight initialization before batchers are created

3. Add exponential backoff retry logic:
   - SpotlightClient now implements proper exponential backoff when the
     Spotlight server is unreachable
   - Skips sending during backoff period to avoid blocking
   - Logs errors only once per backoff cycle

4. Update tests:
   - Fix test expectation for spotlight=True + env URL case
   - Add tests for warning scenarios
   - Add test for session envelope routing to Spotlight

Author: BYK

sentry_sdk/client.py

@@ -389,68 +389,17 @@ def _record_lost_event(
                 if self.options["enable_backpressure_handling"]:
                     self.monitor = Monitor(self.transport)
 
-            # Setup Spotlight before creating batchers so _capture_envelope can use it
-            spotlight_config = self.options.get("spotlight")
-            spotlight_env_value = os.environ.get("SENTRY_SPOTLIGHT")
-
-            # Parse env var to determine if it's a boolean or URL
-            spotlight_from_env = None  # type: Optional[bool]
-            spotlight_env_url = None  # type: Optional[str]
-            if spotlight_env_value:
-                parsed = env_to_bool(spotlight_env_value, strict=True)
-                if parsed is None:
-                    # It's a URL string
-                    spotlight_from_env = True
-                    spotlight_env_url = spotlight_env_value
-                else:
-                    spotlight_from_env = parsed
-
-            # Apply precedence rules per spec
-            if spotlight_config is False:
-                # Config explicitly disables spotlight - warn if env var was set
-                if spotlight_from_env:
-                    logger.warning(
-                        "Spotlight is disabled via spotlight=False config option, "
-                        "ignoring SENTRY_SPOTLIGHT environment variable."
-                    )
-                self.options["spotlight"] = False
-            elif spotlight_config is True:
-                # Config enables spotlight with boolean true
-                # If env var has URL, use env var URL per spec
-                if spotlight_env_url:
-                    self.options["spotlight"] = spotlight_env_url
-                else:
-                    self.options["spotlight"] = True
-            elif isinstance(spotlight_config, str):
-                # Config has URL string - use config URL, warn if env var differs
-                if spotlight_env_value and spotlight_env_value != spotlight_config:
-                    logger.warning(
-                        "Spotlight URL from config (%s) takes precedence over "
-                        "SENTRY_SPOTLIGHT environment variable (%s).",
-                        spotlight_config,
-                        spotlight_env_value,
-                    )
-                # self.options["spotlight"] already has the config URL
-            elif spotlight_config is None:
-                # No config - use env var
-                if spotlight_env_url:
-                    self.options["spotlight"] = spotlight_env_url
-                elif spotlight_from_env:
-                    self.options["spotlight"] = True
-                # else: stays None (disabled)
-
-            if self.options.get("spotlight"):
-                # This is intentionally here to prevent setting up spotlight
-                # stuff we don't need unless spotlight is explicitly enabled
-                from sentry_sdk.spotlight import setup_spotlight
-
-                self.spotlight = setup_spotlight(self.options)
-                if not self.options["dsn"]:
-                    sample_all = lambda *_args, **_kwargs: 1.0
-                    self.options["send_default_pii"] = True
-                    self.options["error_sampler"] = sample_all
-                    self.options["traces_sampler"] = sample_all
-                    self.options["profiles_sampler"] = sample_all
+            # Setup Spotlight before creating batchers so _capture_envelope can use it.
+            # setup_spotlight handles all config/env var resolution per the SDK spec.
+            from sentry_sdk.spotlight import setup_spotlight
+
+            self.spotlight = setup_spotlight(self.options)
+            if self.spotlight is not None and not self.options["dsn"]:
+                sample_all = lambda *_args, **_kwargs: 1.0
+                self.options["send_default_pii"] = True
+                self.options["error_sampler"] = sample_all
+                self.options["traces_sampler"] = sample_all
+                self.options["profiles_sampler"] = sample_all
 
             self.session_flusher = SessionFlusher(capture_func=_capture_envelope)
 

sentry_sdk/spotlight.py

@@ -53,17 +53,15 @@ def __init__(self, url):
         # type: (str) -> None
         self.url = url
         self.http = urllib3.PoolManager()
-        self._error_logged = False
         self._retry_delay = self.INITIAL_RETRY_DELAY
         self._last_error_time = 0.0  # type: float
 
     def capture_envelope(self, envelope):
         # type: (Envelope) -> None
 
         # Check if we're in backoff period - skip sending to avoid blocking
-        current_time = time.time()
         if self._last_error_time > 0:
-            time_since_error = current_time - self._last_error_time
+            time_since_error = time.time() - self._last_error_time
             if time_since_error < self._retry_delay:
                 # Still in backoff period, skip this envelope
                 return
@@ -81,27 +79,23 @@ def capture_envelope(self, envelope):
             )
             req.close()
             # Success - reset backoff state
-            self._error_logged = False
             self._retry_delay = self.INITIAL_RETRY_DELAY
             self._last_error_time = 0.0
         except Exception as e:
-            current_time = time.time()
-            self._last_error_time = current_time
+            self._last_error_time = time.time()
 
-            # Log error only once per backoff cycle
-            if not self._error_logged:
-                sentry_logger.warning(
-                    "Failed to send envelope to Spotlight at %s: %s. "
-                    "Will retry after %.1f seconds.",
-                    self.url,
-                    e,
-                    self._retry_delay,
-                )
-                self._error_logged = True
-
-            # Increase backoff delay exponentially
+            # Increase backoff delay exponentially first, so logged value matches actual wait
             self._retry_delay = min(self._retry_delay * 2, self.MAX_RETRY_DELAY)
 
+            # Log error once per backoff cycle (we skip sends during backoff, so only one failure per cycle)
+            sentry_logger.warning(
+                "Failed to send envelope to Spotlight at %s: %s. "
+                "Will retry after %.1f seconds.",
+                self.url,
+                e,
+                self._retry_delay,
+            )
+
 
 try:
     from django.utils.deprecation import MiddlewareMixin
@@ -242,20 +236,83 @@ def process_exception(self, _request, exception):
     settings = None
 
 
+def _resolve_spotlight_url(spotlight_config, sentry_logger):
+    # type: (Any, Any) -> Optional[str]
+    """
+    Resolve the Spotlight URL based on config and environment variable.
+
+    Implements precedence rules per the SDK spec:
+    https://develop.sentry.dev/sdk/expected-features/spotlight/
+
+    Returns the resolved URL string, or None if Spotlight should be disabled.
+    """
+    spotlight_env_value = os.environ.get("SENTRY_SPOTLIGHT")
+
+    # Parse env var to determine if it's a boolean or URL
+    spotlight_from_env = None  # type: Optional[bool]
+    spotlight_env_url = None  # type: Optional[str]
+    if spotlight_env_value:
+        parsed = env_to_bool(spotlight_env_value, strict=True)
+        if parsed is None:
+            # It's a URL string
+            spotlight_from_env = True
+            spotlight_env_url = spotlight_env_value
+        else:
+            spotlight_from_env = parsed
+
+    # Apply precedence rules per spec:
+    # https://develop.sentry.dev/sdk/expected-features/spotlight/#precedence-rules
+    if spotlight_config is False:
+        # Config explicitly disables spotlight - warn if env var was set
+        if spotlight_from_env:
+            sentry_logger.warning(
+                "Spotlight is disabled via spotlight=False config option, "
+                "ignoring SENTRY_SPOTLIGHT environment variable."
+            )
+        return None
+    elif spotlight_config is True:
+        # Config enables spotlight with boolean true
+        # If env var has URL, use env var URL per spec
+        if spotlight_env_url:
+            return spotlight_env_url
+        else:
+            return DEFAULT_SPOTLIGHT_URL
+    elif isinstance(spotlight_config, str):
+        # Config has URL string - use config URL, warn if env var differs
+        if spotlight_env_value and spotlight_env_value != spotlight_config:
+            sentry_logger.warning(
+                "Spotlight URL from config (%s) takes precedence over "
+                "SENTRY_SPOTLIGHT environment variable (%s).",
+                spotlight_config,
+                spotlight_env_value,
+            )
+        return spotlight_config
+    elif spotlight_config is None:
+        # No config - use env var
+        if spotlight_env_url:
+            return spotlight_env_url
+        elif spotlight_from_env:
+            return DEFAULT_SPOTLIGHT_URL
+        # else: stays None (disabled)
+
+    return None
+
+
 def setup_spotlight(options):
     # type: (Dict[str, Any]) -> Optional[SpotlightClient]
+    url = _resolve_spotlight_url(options.get("spotlight"), sentry_logger)
+
+    if url is None:
+        return None
+
+    # Only set up logging handler when spotlight is actually enabled
     _handler = logging.StreamHandler(sys.stderr)
     _handler.setFormatter(logging.Formatter(" [spotlight] %(levelname)s: %(message)s"))
     logger.addHandler(_handler)
     logger.setLevel(logging.INFO)
 
-    url = options.get("spotlight")
-
-    if url is True:
-        url = DEFAULT_SPOTLIGHT_URL
-
-    if not isinstance(url, str):
-        return None
+    # Update options with resolved URL for consistency
+    options["spotlight"] = url
 
     with capture_internal_exceptions():
         if (