bugsnag: chain-aware grouping key and chain title in error list (#262)

`normalize_error_chain` walks `__cause__`/`__context__` and joins each level's normalized string with `" <- "`. This replaces the single-exception `normalize_error_message` call used for the grouping key so that `"LauncherError <- TimeoutError"` and `"LauncherError <- ApiException"` land in separate, stable groups rather than collapsing into one group per root cause.

`build_chain_title` does the same walk but truncates each level to 80 chars and returns `None` for single exceptions. `_before_notify` uses it to override the root-cause `errorClass` that Bugsnag displays in the error list, giving reviewers the full raise path at a glance without needing to open the stacktrace.

Author: morgan-wowk

cloud_pipelines_backend/instrumentation/bugsnag_instrumentation.py

@@ -43,20 +43,36 @@ def _before_notify(event: bugsnag_event.Event) -> None:
     if context:
         event.add_tab("tangle_context", context)
     if _CUSTOM_GROUPING_KEY and event.original_error:
-        normalized = error_normalization.normalize_error_message(
+        # Use the full chain for grouping so that "LauncherError <- TimeoutError"
+        # and "LauncherError <- ApiException" land in separate, stable groups.
+        chain = error_normalization.normalize_error_chain(
             exception=event.original_error
         )
         prefix = (event.metadata.get("extra") or {}).get("grouping_prefix")
-        key_value = f"{prefix}: {normalized}" if prefix else normalized
+        key_value = f"{prefix}: {chain}" if prefix else chain
         event.add_tab("custom", {_CUSTOM_GROUPING_KEY: key_value})
         if prefix and event.errors:
             try:
                 for error in event.errors:
                     error.error_class = f"{prefix}: {error.error_class}"
             except Exception:
-                _logger.debug(
+                _logger.warning(
                     "Could not prepend grouping prefix to errorClass", exc_info=True
                 )
+        # For chained exceptions, override the root-cause title (what Bugsnag
+        # displays in the error list) with the full chain so reviewers can see
+        # the complete raise path without opening the stacktrace.
+        chain_title = error_normalization.build_chain_title(
+            exception=event.original_error
+        )
+        if chain_title and event.errors:
+            try:
+                title = f"{prefix}: {chain_title}" if prefix else chain_title
+                event.errors[-1].error_class = title
+            except Exception:
+                _logger.warning(
+                    "Could not set chain title on errorClass", exc_info=True
+                )
 
 
 def setup(*, service_name: str | None = None) -> None:

cloud_pipelines_backend/instrumentation/error_normalization.py

@@ -107,7 +107,7 @@ def _normalize_launcher_error(*, exception: BaseException) -> str | None:
 
 
 def normalize_error_message(*, exception: BaseException) -> str:
-    """Return a stable normalized string for error grouping."""
+    """Return a stable normalized string for a single exception (no chain traversal)."""
     for normalizer in (
         _normalize_k8s_api_exception,
         _normalize_max_retry_error,
@@ -120,3 +120,53 @@ def normalize_error_message(*, exception: BaseException) -> str:
             return result
 
     return f"{type(exception).__name__}: {_strip_generic(message=str(exception))}"
+
+
+_CHAIN_PART_MAX_LEN = 80
+_CHAIN_GROUPING_KEY_MAX_PART_LEN = 200
+_CHAIN_MAX_DEPTH = 4
+
+
+def _walk_chain(exception: BaseException) -> list[BaseException]:
+    """Return the exception chain up to ``_CHAIN_MAX_DEPTH`` levels, cycle-safe."""
+    excs: list[BaseException] = []
+    seen: set[int] = set()
+    exc: BaseException | None = exception
+    while exc is not None and id(exc) not in seen and len(excs) < _CHAIN_MAX_DEPTH:
+        seen.add(id(exc))
+        excs.append(exc)
+        exc = exc.__cause__ or (None if exc.__suppress_context__ else exc.__context__)
+    return excs
+
+
+def normalize_error_chain(*, exception: BaseException) -> str:
+    """Return a stable normalized string covering the full exception chain.
+
+    Walks ``__cause__`` (and ``__context__`` when not suppressed) and joins
+    each level with `` <- ``.  Use this for grouping keys so that chained
+    exceptions like ``LauncherError <- TimeoutError`` produce one stable group
+    rather than one per root cause.
+    """
+    parts = [
+        normalize_error_message(exception=exc)[:_CHAIN_GROUPING_KEY_MAX_PART_LEN]
+        for exc in _walk_chain(exception)
+    ]
+    return " <- ".join(parts)
+
+
+def build_chain_title(*, exception: BaseException) -> str | None:
+    """Return a human-readable chain title for display, or ``None`` for single exceptions.
+
+    Like ``normalize_error_chain`` but truncates each level so the result fits
+    in a Bugsnag error list title.  Returns ``None`` when there is no
+    chain so callers can skip overriding the default title.
+    """
+    parts: list[str] = []
+    for exc in _walk_chain(exception):
+        part = normalize_error_message(exception=exc)
+        if len(part) > _CHAIN_PART_MAX_LEN:
+            part = part[:_CHAIN_PART_MAX_LEN].rstrip() + "..."
+        parts.append(part)
+    if len(parts) <= 1:
+        return None
+    return " <- ".join(parts)

tests/instrumentation/test_error_normalization.py

@@ -260,3 +260,76 @@ def test_strips_json_object_double_quotes(self):
         exc = RuntimeError('operation failed: {"key": "value"}')
         result = error_normalization.normalize_error_message(exception=exc)
         assert result == "RuntimeError: operation failed: {...}"
+
+
+class TestNormalizeErrorChain:
+    def _chained(
+        self, outer_msg: str, inner: BaseException, outer_cls: type = RuntimeError
+    ) -> BaseException:
+        try:
+            raise outer_cls(outer_msg) from inner
+        except outer_cls as exc:
+            return exc
+
+    def test_single_exception_no_arrow(self):
+        exc = ValueError("something went wrong")
+        result = error_normalization.normalize_error_chain(exception=exc)
+        assert result == "ValueError: something went wrong"
+        assert " <- " not in result
+
+    def test_two_level_chain(self):
+        inner = TimeoutError("The read operation timed out")
+        outer = self._chained("Failed to create pod: {'apiVersion': 'v1'}", inner)
+        result = error_normalization.normalize_error_chain(exception=outer)
+        assert result == (
+            "RuntimeError: Failed to create pod: {...} <- TimeoutError: The read operation timed out"
+        )
+
+    def test_launcher_error_chain(self):
+        try:
+            from cloud_pipelines_backend.launchers.interfaces import LauncherError
+        except ImportError:
+            pytest.skip("LauncherError not importable")
+        inner = TimeoutError("The read operation timed out")
+        try:
+            raise LauncherError("Failed to create pod: {spec}") from inner
+        except LauncherError as outer:
+            result = error_normalization.normalize_error_chain(exception=outer)
+        assert result == (
+            "LauncherError: Failed to create pod: {spec} <- TimeoutError: The read operation timed out"
+        )
+
+    def test_caps_at_four_levels(self):
+        exc: BaseException = ValueError("level 4")
+        for i in range(3, 0, -1):
+            exc = self._chained(f"level {i}", exc)
+        # Chain is 4 deep; add a 5th
+        exc = self._chained("level 0", exc)
+        result = error_normalization.normalize_error_chain(exception=exc)
+        assert result.count(" <- ") == 3  # 4 parts max
+
+
+class TestBuildChainTitle:
+    def test_single_exception_returns_none(self):
+        exc = ValueError("nothing to chain")
+        assert error_normalization.build_chain_title(exception=exc) is None
+
+    def test_two_level_chain_returns_string(self):
+        inner = TimeoutError("The read operation timed out")
+        try:
+            raise RuntimeError("outer problem") from inner
+        except RuntimeError as outer:
+            result = error_normalization.build_chain_title(exception=outer)
+        assert result == (
+            "RuntimeError: outer problem <- TimeoutError: The read operation timed out"
+        )
+
+    def test_truncates_long_parts(self):
+        inner = ValueError("x" * 200)
+        try:
+            raise RuntimeError("outer") from inner
+        except RuntimeError as outer:
+            result = error_normalization.build_chain_title(exception=outer)
+        assert result is not None
+        inner_part = result.split(" <- ")[1]
+        assert len(inner_part) <= 83  # 80 + "..."