feat(error-tracking): standardize exception event metadata

.sampo/changesets/canonical-exception-metadata.md

@@ -0,0 +1,5 @@
+---
+pypi/posthog: minor
+---
+
+Standardize exception capture metadata, including severity, capture source, mechanism semantics, deterministic cause linkage, and reserved property ownership.

posthog/client.py

@@ -57,6 +57,7 @@
     _get_current_otel_span_properties,
     handle_in_app,
     mark_exception_as_captured,
+    _normalize_exception_level,
     try_attach_code_variables_to_frames,
 )
 from posthog.feature_flag_evaluations import (
@@ -2056,7 +2057,16 @@ def capture_exception(
                 return None
 
             # Format stack trace for cymbal
-            all_exceptions_with_trace = exceptions_from_error_tuple(exc_info)
+            capture_metadata_input = dict(kwargs).get("_capture_metadata")
+            capture_metadata = (
+                capture_metadata_input
+                if isinstance(capture_metadata_input, dict)
+                else {}
+            )
+            mechanism = capture_metadata.get("mechanism")
+            all_exceptions_with_trace = exceptions_from_error_tuple(
+                exc_info, mechanism=mechanism if isinstance(mechanism, dict) else None
+            )
 
             # Add in-app property to frames in the exceptions
             event = handle_in_app(
@@ -2070,11 +2080,38 @@ def capture_exception(
             )
             all_exceptions_with_trace_and_in_app = event["exception"]["values"]
 
+            reserved_properties = {
+                "$exception_list",
+                "$exception_level",
+                "$exception_source",
+                "$debug_images",
+                "$exception_handled",
+                "$exception_types",
+                "$exception_values",
+                "$exception_sources",
+                "$exception_functions",
+                "$exception_fingerprint_version",
+                "$exception_fingerprint_record",
+                "$exception_issue_id",
+                "$exception_release",
+                "$cymbal_errors",
+            }
             properties = {
-                "$exception_list": all_exceptions_with_trace_and_in_app,
                 **_get_current_otel_span_properties(),
-                **properties,
+                **{
+                    key: value
+                    for key, value in properties.items()
+                    if key not in reserved_properties
+                },
+                "$exception_list": all_exceptions_with_trace_and_in_app,
+                "$exception_level": _normalize_exception_level(
+                    capture_metadata.get("level")
+                )
+                or "error",
             }
+            source = capture_metadata.get("source")
+            if isinstance(source, str) and source:
+                properties["$exception_source"] = source
 
             context_enabled = get_capture_exception_code_variables_context()
             context_mask = get_code_variables_mask_patterns_context()

posthog/exception_capture.py

@@ -10,6 +10,7 @@
 from typing import TYPE_CHECKING
 
 from posthog.bucketed_rate_limiter import BucketedRateLimiter
+from .exception_utils import _capture_exception_with_metadata
 
 if TYPE_CHECKING:
     from posthog.client import Client
@@ -80,7 +81,17 @@ def close(self):
 
     def exception_handler(self, exc_type, exc_value, exc_traceback):
         if not self._closed:
-            self.capture_exception((exc_type, exc_value, exc_traceback))
+            self._capture_exception(
+                (exc_type, exc_value, exc_traceback),
+                capture_metadata={
+                    "level": "fatal",
+                    "source": "python.sys_excepthook",
+                    "mechanism": {
+                        "type": "onuncaughtexception",
+                        "handled": False,
+                    },
+                },
+            )
         previous_hook = self._resolve_hook(
             self.original_excepthook,
             "exception_handler",
@@ -90,7 +101,17 @@ def exception_handler(self, exc_type, exc_value, exc_traceback):
 
     def thread_exception_handler(self, args):
         if not self._closed:
-            self.capture_exception((args.exc_type, args.exc_value, args.exc_traceback))
+            self._capture_exception(
+                (args.exc_type, args.exc_value, args.exc_traceback),
+                capture_metadata={
+                    "level": "error",
+                    "source": "python.threading_excepthook",
+                    "mechanism": {
+                        "type": "onuncaughtexception",
+                        "handled": False,
+                    },
+                },
+            )
         previous_hook = self._resolve_hook(
             self._original_threading_excepthook,
             "thread_exception_handler",
@@ -117,6 +138,9 @@ def exception_receiver(self, exc_info, extra_properties):
         self.capture_exception((exc_info[0], exc_info[1], exc_info[2]), metadata)
 
     def capture_exception(self, exception, metadata=None):
+        self._capture_exception(exception, metadata)
+
+    def _capture_exception(self, exception, metadata=None, capture_metadata=None):
         try:
             if self._rate_limiter is not None:
                 exception_type = self._exception_type(exception)
@@ -127,7 +151,12 @@ def capture_exception(self, exception, metadata=None):
                     return
 
             distinct_id = metadata.get("distinct_id") if metadata else None
-            self.client.capture_exception(exception, distinct_id=distinct_id)
+            _capture_exception_with_metadata(
+                self.client,
+                exception,
+                capture_metadata or {},
+                distinct_id=distinct_id,
+            )
         except Exception as e:
             self.log.exception(f"Failed to capture exception: {e}")