fix(serializer): add depth limit to EventSerializer to prevent hangs on complex objects (#1577)

* fix: add depth limit to EventSerializer to prevent hangs on complex objects

EventSerializer.default() recursively traverses __dict__ and __slots__
of arbitrary objects without a depth limit. When @observe() captures
function arguments containing objects like google.genai.Client (which
hold aiohttp sessions, connection pools, and threading locks),
json.dumps blocks indefinitely on the second invocation.

Add a _MAX_DEPTH=20 counter that returns a <TypeName> placeholder
when exceeded, preventing infinite recursion into complex object graphs
while preserving all existing serialization behavior.

* test: tighten slots depth assertion to reflect double depth-counting

* fix: claude comments

Author: BKDDFS

langfuse/_utils/serializer.py

@@ -36,11 +36,21 @@ class Serializable:  # type: ignore
 
 
 class EventSerializer(JSONEncoder):
+    _MAX_DEPTH = 20
+
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.seen: set[int] = set()  # Track seen objects to detect circular references
+        self._depth = 0
 
     def default(self, obj: Any) -> Any:
+        self._depth += 1
+        try:
+            return self._default_inner(obj)
+        finally:
+            self._depth -= 1
+
+    def _default_inner(self, obj: Any) -> Any:
         try:
             if isinstance(obj, (datetime)):
                 # Timezone-awareness check
@@ -82,9 +92,6 @@ def default(self, obj: Any) -> Any:
             if isinstance(obj, Queue):
                 return type(obj).__name__
 
-            if is_dataclass(obj):
-                return asdict(obj)  # type: ignore
-
             if isinstance(obj, UUID):
                 return str(obj)
 
@@ -97,22 +104,9 @@ def default(self, obj: Any) -> Any:
             if isinstance(obj, (date)):
                 return obj.isoformat()
 
-            if isinstance(obj, BaseModel):
-                obj.model_rebuild()
-
-                # For LlamaIndex models, we need to rebuild the raw model as well if they include OpenAI models
-                if isinstance(raw := getattr(obj, "raw", None), BaseModel):
-                    raw.model_rebuild()
-
-                return obj.model_dump()
-
             if isinstance(obj, Path):
                 return str(obj)
 
-            # if langchain is not available, the Serializable type is NoneType
-            if Serializable is not type(None) and isinstance(obj, Serializable):  # type: ignore
-                return obj.to_json()
-
             # 64-bit integers might overflow the JavaScript safe integer range.
             # Since Node.js is run on the server that handles the serialized value,
             # we need to ensure that integers outside the safe range are converted to strings.
@@ -123,6 +117,25 @@ def default(self, obj: Any) -> Any:
             if isinstance(obj, (str, float, type(None))):
                 return obj
 
+            if self._depth >= self._MAX_DEPTH:
+                return f"<{type(obj).__name__}>"
+
+            if is_dataclass(obj):
+                return asdict(obj)  # type: ignore
+
+            if isinstance(obj, BaseModel):
+                obj.model_rebuild()
+
+                # For LlamaIndex models, we need to rebuild the raw model as well if they include OpenAI models
+                if isinstance(raw := getattr(obj, "raw", None), BaseModel):
+                    raw.model_rebuild()
+
+                return obj.model_dump()
+
+            # if langchain is not available, the Serializable type is NoneType
+            if Serializable is not type(None) and isinstance(obj, Serializable):  # type: ignore
+                return obj.to_json()
+
             if isinstance(obj, (tuple, set, frozenset)):
                 return list(obj)
 
@@ -138,9 +151,10 @@ def default(self, obj: Any) -> Any:
                 return [self.default(item) for item in obj]
 
             if hasattr(obj, "__slots__"):
-                return self.default(
-                    {slot: getattr(obj, slot, None) for slot in obj.__slots__}
-                )
+                return {
+                    slot: self.default(getattr(obj, slot, None))
+                    for slot in obj.__slots__
+                }
             elif hasattr(obj, "__dict__"):
                 obj_id = id(obj)
 
@@ -167,6 +181,7 @@ def default(self, obj: Any) -> Any:
 
     def encode(self, obj: Any) -> str:
         self.seen.clear()  # Clear seen objects before each encode call
+        self._depth = 0
 
         try:
             return super().encode(self.default(obj))

tests/unit/test_serializer.py

@@ -6,6 +6,7 @@
 from pathlib import Path
 from uuid import UUID
 
+import pytest
 from pydantic import BaseModel
 
 from langfuse._utils.serializer import (
@@ -174,3 +175,126 @@ def __init__(self):
     obj = SlotClass()
     serializer = EventSerializer()
     assert json.loads(serializer.encode(obj)) == {"field": "value"}
+
+
+def test_deeply_nested_object_does_not_hang():
+    class Inner:
+        def __init__(self):
+            self.lock = threading.Lock()
+            self.value = "deep"
+
+    class Connection:
+        def __init__(self):
+            self._inner = Inner()
+            self._pool = [Inner() for _ in range(3)]
+
+    class Client:
+        def __init__(self):
+            self._connection = Connection()
+            self._config = {"key": "value"}
+
+    class Platform:
+        def __init__(self):
+            self._client = Client()
+
+    obj = {"args": (Platform(),), "kwargs": {}}
+    serializer = EventSerializer()
+    result = serializer.encode(obj)
+
+    # Must complete without hanging and produce valid JSON
+    parsed = json.loads(result)
+    assert "args" in parsed
+
+
+def test_max_depth_returns_type_name():
+    class Level:
+        def __init__(self, child=None):
+            self.child = child
+
+    # Build a chain deeper than _MAX_DEPTH
+    obj = None
+    for _ in range(EventSerializer._MAX_DEPTH + 10):
+        obj = Level(child=obj)
+
+    serializer = EventSerializer()
+    result = json.loads(serializer.encode(obj))
+
+    # Walk down the chain — at some point it should be truncated to "Level"
+    node = result
+    found_truncation = False
+    while isinstance(node, dict) and "child" in node:
+        if node["child"] == "Level" or node["child"] == "<Level>":
+            found_truncation = True
+            break
+        node = node["child"]
+
+    assert found_truncation, "Expected depth limit to truncate deep nesting"
+
+
+def test_deeply_nested_slots_object_is_truncated():
+    class SlotLevel:
+        __slots__ = ["child"]
+
+        def __init__(self, child=None):
+            self.child = child
+
+    obj = None
+    for _ in range(EventSerializer._MAX_DEPTH + 10):
+        obj = SlotLevel(child=obj)
+
+    serializer = EventSerializer()
+    result = json.loads(serializer.encode(obj))
+
+    # Walk the nested structure and verify it terminates
+    node = result
+    depth = 0
+    while isinstance(node, dict):
+        depth += 1
+        if "child" in node:
+            node = node["child"]
+        else:
+            break
+
+    assert EventSerializer._MAX_DEPTH - 2 <= depth <= EventSerializer._MAX_DEPTH + 2, (
+        f"Nesting depth {depth} not near _MAX_DEPTH ({EventSerializer._MAX_DEPTH}) — "
+        "serializer truncated too early or too late"
+    )
+
+
+def test_deeply_nested_dict_preserves_keys_at_depth_boundary(monkeypatch):
+    monkeypatch.setattr(EventSerializer, "_MAX_DEPTH", 3)
+
+    input_obj = {"a": {"b": {"c": "leaf"}}}
+    expected = {"a": {"b": "<dict>"}}
+
+    serializer = EventSerializer()
+    result = json.loads(serializer.encode(input_obj))
+
+    assert result == expected
+
+
+class _Color(Enum):
+    RED = "red"
+    NUMERIC = 7
+
+
+@pytest.mark.parametrize(
+    "input_obj, expected",
+    [
+        (
+            {datetime(2024, 1, 1, tzinfo=timezone.utc): "v"},
+            {"2024-01-01T00:00:00Z": "v"},
+        ),
+        (
+            {UUID("12345678-1234-5678-1234-567812345678"): "v"},
+            {"12345678-1234-5678-1234-567812345678": "v"},
+        ),
+        ({_Color.RED: "v"}, {"red": "v"}),
+        ({_Color.NUMERIC: "v"}, {"7": "v"}),
+    ],
+    ids=["datetime", "uuid", "enum_str_value", "enum_int_value"],
+)
+def test_dict_with_non_string_keys_is_serialized(input_obj, expected):
+    result = json.loads(EventSerializer().encode(input_obj))
+
+    assert result == expected