feat(drf): support exception capture opt-out

Author: hpouillot

.sampo/changesets/django-rest-framework-error-tracking.md

@@ -2,4 +2,4 @@
 pypi/posthog: minor
 ---
 
-Add a Django REST Framework exception handler integration that automatically captures handled 5xx API exceptions while preserving DRF responses and leaving expected 4xx errors excluded by default.
+Add a Django REST Framework exception handler integration that automatically captures handled 5xx API exceptions while preserving DRF responses, leaving expected 4xx errors excluded by default, and honoring exception-capture opt-outs.

posthog/integrations/drf.py

@@ -10,8 +10,11 @@
     }
 
 By default, only responses with a 5xx status are captured. Expected 4xx API
-errors are ignored. Projects that already have a custom DRF exception handler
-can wrap it in an application module::
+errors are ignored. Set ``POSTHOG_MW_CAPTURE_EXCEPTIONS = False`` to keep the
+Django request context without capturing Django or DRF exceptions.
+
+Projects that already have a custom DRF exception handler can wrap it in an
+application module::
 
     from myapp.api import existing_exception_handler
     from posthog.integrations.drf import create_exception_handler
@@ -66,6 +69,21 @@ def _configured_client(client: Optional[Client]) -> Optional[Client]:
     return None
 
 
+def _capture_exceptions_enabled(configured: Optional[bool]) -> bool:
+    """Resolve explicit configuration before the shared Django middleware setting."""
+    if configured is not None:
+        return configured
+
+    try:
+        from django.conf import settings
+
+        django_setting = getattr(settings, "POSTHOG_MW_CAPTURE_EXCEPTIONS", None)
+    except Exception:
+        return True
+
+    return django_setting if isinstance(django_setting, bool) else True
+
+
 def _passes_django_request_filter(context: Mapping[str, Any]) -> bool:
     """Apply the Django middleware request filter to the underlying request."""
     try:
@@ -102,6 +120,7 @@ def create_exception_handler(
     handler: Optional[Callable[[Exception, Mapping[str, Any]], Any]] = None,
     *,
     client: Optional[Client] = None,
+    capture_exceptions: Optional[bool] = None,
     capture_4xx: bool = False,
     exception_filter: Optional[
         Callable[[Exception, Any, Mapping[str, Any]], bool]
@@ -115,6 +134,9 @@ def create_exception_handler(
         client: Optional PostHog client. When omitted, ``POSTHOG_DRF_CLIENT`` or
             ``POSTHOG_MW_CLIENT`` is used when configured, then the global
             PostHog client.
+        capture_exceptions: Whether to capture handled DRF exceptions. When
+            omitted, inherits a boolean ``POSTHOG_MW_CAPTURE_EXCEPTIONS`` setting
+            and otherwise defaults to ``True``. An explicit value takes precedence.
         capture_4xx: Also capture handled 4xx responses. Disabled by default to
             avoid reporting expected API errors.
         exception_filter: Optional final filter called with ``(exception,
@@ -134,6 +156,8 @@ def posthog_exception_handler(exc: Exception, context: Mapping[str, Any]) -> Any
         response = delegate(exc, context)
         if response is None:
             return None
+        if not _capture_exceptions_enabled(capture_exceptions):
+            return response
 
         try:
             status_code = int(response.status_code)

posthog/test/integrations/test_drf_integration.py

@@ -107,6 +107,51 @@ def test_custom_handler_exception_is_preserved(self):
 
         client.capture_exception.assert_not_called()
 
+    def test_explicit_capture_opt_out_preserves_response_without_running_filters(self):
+        client = Mock()
+        response = Response({"detail": "unavailable"}, status=503)
+        delegate = Mock(return_value=response)
+        exception_filter = Mock(return_value=True)
+        request_filter = Mock(return_value=True)
+        handler = create_exception_handler(
+            delegate,
+            client=client,
+            capture_exceptions=False,
+            exception_filter=exception_filter,
+        )
+        exception = RuntimeError("upstream failed")
+        context = {"request": object()}
+
+        with override_settings(POSTHOG_MW_REQUEST_FILTER=request_filter):
+            returned_response = handler(exception, context)
+
+        self.assertIs(returned_response, response)
+        delegate.assert_called_once_with(exception, context)
+        request_filter.assert_not_called()
+        exception_filter.assert_not_called()
+        client.capture_exception.assert_not_called()
+
+    @override_settings(POSTHOG_MW_CAPTURE_EXCEPTIONS=False)
+    def test_module_handler_inherits_django_capture_opt_out(self):
+        exception = ServiceUnavailable()
+
+        with patch("posthog.capture_exception") as capture_exception:
+            response = exception_handler(exception, {})
+
+        self.assertEqual(response.status_code, 503)
+        capture_exception.assert_not_called()
+
+    @override_settings(POSTHOG_MW_CAPTURE_EXCEPTIONS=False)
+    def test_explicit_capture_setting_overrides_django_opt_out(self):
+        client = Mock()
+        handler = create_exception_handler(client=client, capture_exceptions=True)
+        exception = ServiceUnavailable()
+
+        response = handler(exception, {})
+
+        self.assertEqual(response.status_code, 503)
+        client.capture_exception.assert_called_once()
+
     @override_settings(POSTHOG_MW_REQUEST_FILTER=lambda request: False)
     def test_django_middleware_request_filter_suppresses_capture(self):
         client = Mock()

references/public_api_snapshot.txt

@@ -1404,7 +1404,7 @@ function posthog.get_tags() -> Dict[str, Any]
 function posthog.group_identify(group_type: str, group_key: str, properties: Optional[Dict[str, Any]] = None, timestamp: Optional[Union[datetime.datetime, str]] = None, uuid: Optional[str] = None, disable_geoip: Optional[bool] = None, distinct_id: Optional[ID_TYPES] = None) -> Optional[str]
 function posthog.identify_context(distinct_id: str)
 function posthog.integrations.django.markcoroutinefunction(func)
-function posthog.integrations.drf.create_exception_handler(handler: Optional[Callable[[Exception, Mapping[str, Any]], Any]] = None, *, client: Optional[Client] = None, capture_4xx: bool = False, exception_filter: Optional[Callable[[Exception, Any, Mapping[str, Any]], bool]] = None) -> Callable[[Exception, Mapping[str, Any]], Any]
+function posthog.integrations.drf.create_exception_handler(handler: Optional[Callable[[Exception, Mapping[str, Any]], Any]] = None, *, client: Optional[Client] = None, capture_exceptions: Optional[bool] = None, capture_4xx: bool = False, exception_filter: Optional[Callable[[Exception, Any, Mapping[str, Any]], bool]] = None) -> Callable[[Exception, Mapping[str, Any]], Any]
 function posthog.integrations.drf.exception_handler(exc: Exception, context: Mapping[str, Any]) -> Any
 function posthog.join() -> None
 function posthog.load_feature_flags()