Include notes when logging exceptions

CHANGELOG.md

@@ -27,6 +27,9 @@ You can find our backwards-compatibility policy [here](https://github.com/hynek/
 
   [#647](https://github.com/hynek/structlog/pull/647)
 
+- `structlog.tracebacks.Stack` now includes an `exc_notes` field reflecting the notes attached to the exception.
+
+  [#684](https://github.com/hynek/structlog/pull/684)
 
 ## Fixed
 

docs/api.rst

@@ -197,7 +197,7 @@ API Reference
          ...     1 / 0
          ... except ZeroDivisionError:
          ...     log.exception("Cannot compute!")
-         {"event": "Cannot compute!", "exception": [{"exc_type": "ZeroDivisionError", "exc_value": "division by zero", "syntax_error": null, "is_cause": false, "frames": [{"filename": "<doctest default[3]>", "lineno": 2, "name": "<module>", "locals": {..., "var": "'spam'"}}]}]}
+         {"event": "Cannot compute!", "exception": [{"exc_type": "ZeroDivisionError", "exc_value": "division by zero", "exc_notes": null, "syntax_error": null, "is_cause": false, "frames": [{"filename": "<doctest default[3]>", "lineno": 2, "name": "<module>", "locals": {..., "var": "'spam'"}}]}]}
 
 .. autoclass:: KeyValueRenderer
 

src/structlog/tracebacks.py

@@ -83,10 +83,14 @@ class SyntaxError_:  # noqa: N801
 class Stack:
     """
     Represents an exception and a list of stack frames.
+
+    .. versionchanged:: 24.5.0
+       Added the *exc_notes* field.
     """
 
     exc_type: str
     exc_value: str
+    exc_notes: str | None = None
     syntax_error: SyntaxError_ | None = None
     is_cause: bool = False
     frames: list[Frame] = field(default_factory=list)
@@ -232,6 +236,11 @@ def extract(
         stack = Stack(
             exc_type=safe_str(exc_type.__name__),
             exc_value=safe_str(exc_value),
+            exc_notes=(
+                "\n".join(safe_str(note) for note in exc_value.__notes__)
+                if hasattr(exc_value, "__notes__")
+                else None
+            ),
             is_cause=is_cause,
         )
 

tests/test_tracebacks.py

@@ -158,6 +158,40 @@ def test_simple_exception():
     ] == trace.stacks
 
 
+@pytest.mark.skipif(
+    sys.version_info < (3, 11), reason="Requires Python 3.11 or higher"
+)
+def test_simple_exception_with_notes():
+    """
+    Notes are included in the traceback.
+    """
+    try:
+        lineno = get_next_lineno()
+        1 / 0
+    except Exception as e:
+        e.add_note("This is a note.")
+        e.add_note("This is another note.")
+        trace = tracebacks.extract(type(e), e, e.__traceback__)
+
+    assert [
+        tracebacks.Stack(
+            exc_type="ZeroDivisionError",
+            exc_value="division by zero",
+            exc_notes="This is a note.\nThis is another note.",
+            syntax_error=None,
+            is_cause=False,
+            frames=[
+                tracebacks.Frame(
+                    filename=__file__,
+                    lineno=lineno,
+                    name="test_simple_exception_with_notes",
+                    locals=None,
+                ),
+            ],
+        ),
+    ] == trace.stacks
+
+
 def test_raise_hide_cause():
     """
     If "raise ... from None" is used, the trace looks like from a simple
@@ -546,6 +580,7 @@ def test_json_traceback():
         {
             "exc_type": "ZeroDivisionError",
             "exc_value": "division by zero",
+            "exc_notes": None,
             "frames": [
                 {
                     "filename": __file__,
@@ -559,6 +594,40 @@ def test_json_traceback():
     ] == result
 
 
+@pytest.mark.skipif(
+    sys.version_info < (3, 11), reason="Requires Python 3.11 or higher"
+)
+def test_json_traceback_with_notes():
+    """
+    Tracebacks are formatted to JSON with all information.
+    """
+    try:
+        lineno = get_next_lineno()
+        1 / 0
+    except Exception as e:
+        e.add_note("This is a note.")
+        e.add_note("This is another note.")
+        format_json = tracebacks.ExceptionDictTransformer(show_locals=False)
+        result = format_json((type(e), e, e.__traceback__))
+
+    assert [
+        {
+            "exc_type": "ZeroDivisionError",
+            "exc_value": "division by zero",
+            "exc_notes": "This is a note.\nThis is another note.",
+            "frames": [
+                {
+                    "filename": __file__,
+                    "lineno": lineno,
+                    "name": "test_json_traceback_with_notes",
+                }
+            ],
+            "is_cause": False,
+            "syntax_error": None,
+        },
+    ] == result
+
+
 def test_json_traceback_locals_max_string():
     """
     Local variables in each frame are trimmed to locals_max_string.
@@ -575,6 +644,7 @@ def test_json_traceback_locals_max_string():
         {
             "exc_type": "ZeroDivisionError",
             "exc_value": "division by zero",
+            "exc_notes": None,
             "frames": [
                 {
                     "filename": __file__,