Skip to content

Commit 871e170

Browse files
niklassemmlerclaude
andcommitted
fix(tracing): JSON-encode metadata attribute values
Per-key `langfuse.observation.metadata.<key>` attributes now carry `json.dumps(value, cls=EventSerializer)` for every value, strings included. Previously str and int were passed raw/natively, so ints beyond int64 made the OTLP encoder drop the key, ints beyond 2^53 lost precision on the server, and a server that JSON-decodes values could not tell the string "123" from the number 123. None values are still skipped so updates keep earlier keys. The bare non-dict metadata attribute is unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent bf11ec1 commit 871e170

5 files changed

Lines changed: 129 additions & 21 deletions

File tree

‎langfuse/_client/attributes.py‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -200,16 +200,22 @@ def _flatten_and_serialize_metadata(
200200
else LangfuseOtelSpanAttributes.TRACE_METADATA
201201
)
202202

203-
metadata_attributes: Dict[str, Union[str, int, None]] = {}
203+
metadata_attributes: Dict[str, Optional[str]] = {}
204204

205205
if not isinstance(metadata, dict):
206206
metadata_attributes[prefix] = _serialize(metadata)
207207
else:
208208
for key, value in metadata.items():
209-
metadata_attributes[f"{prefix}.{key}"] = (
210-
value
211-
if isinstance(value, str) or isinstance(value, int)
212-
else _serialize(value)
209+
# Skip None so an update does not overwrite an earlier value.
210+
if value is None:
211+
continue
212+
213+
# JSON-encode every value, strings included, so the server can decode
214+
# it back to its original type ("123" vs 123). EventSerializer turns
215+
# ints outside the JS-safe range and NaN/Infinity into JSON strings
216+
# and never raises, so one bad value cannot drop the other keys.
217+
metadata_attributes[f"{prefix}.{key}"] = json.dumps(
218+
value, cls=EventSerializer
213219
)
214220

215221
return metadata_attributes

‎tests/unit/test_langchain.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -845,7 +845,7 @@ def test_tool_when_structured_inputs_only_store_in_inputs_attribute_not_metadata
845845

846846
metadata_prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
847847

848-
assert span.attributes[f"{metadata_prefix}.custom_key"] == "custom_value"
848+
assert span.attributes[f"{metadata_prefix}.custom_key"] == '"custom_value"'
849849
assert f"{metadata_prefix}.inputs" not in span.attributes
850850

851851

‎tests/unit/test_openai.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,7 @@ def test_chat_completion_exports_generation_span(
289289
assert (
290290
span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_MODEL] == "gpt-4o-mini"
291291
)
292-
assert span.attributes["langfuse.observation.metadata.suite"] == "unit"
292+
assert span.attributes["langfuse.observation.metadata.suite"] == '"unit"'
293293
assert json_attr(span, LangfuseOtelSpanAttributes.OBSERVATION_INPUT) == [
294294
{"role": "user", "content": "1 + 1 = ?"}
295295
]
@@ -371,7 +371,7 @@ def test_openai_stream_with_none_choices_chunk_does_not_crash(
371371
span = get_span("unit-openai-stream-none-choices")
372372

373373
assert span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT] == "2"
374-
assert span.attributes["langfuse.observation.metadata.finish_reason"] == "stop"
374+
assert span.attributes["langfuse.observation.metadata.finish_reason"] == '"stop"'
375375

376376

377377
def test_streaming_chat_completion_preserves_tool_calls_after_content():
@@ -507,7 +507,7 @@ def fake_stream():
507507
span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_COMPLETION_START_TIME]
508508
is not None
509509
)
510-
assert span.attributes["langfuse.observation.metadata.finish_reason"] == "stop"
510+
assert span.attributes["langfuse.observation.metadata.finish_reason"] == '"stop"'
511511
assert json_attr(span, LangfuseOtelSpanAttributes.OBSERVATION_USAGE_DETAILS) == {
512512
"prompt_tokens": 3,
513513
"completion_tokens": 1,
@@ -575,7 +575,7 @@ def test_openai_stream_preserves_original_stream_contract(
575575
span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_COMPLETION_START_TIME]
576576
is not None
577577
)
578-
assert span.attributes["langfuse.observation.metadata.finish_reason"] == "stop"
578+
assert span.attributes["langfuse.observation.metadata.finish_reason"] == '"stop"'
579579
assert json_attr(span, LangfuseOtelSpanAttributes.OBSERVATION_USAGE_DETAILS) == {
580580
"prompt_tokens": 3,
581581
"completion_tokens": 1,
@@ -610,7 +610,7 @@ def test_openai_stream_handles_trailing_azure_content_filter_chunk(
610610
span = get_span("unit-openai-native-stream-azure-filter")
611611

612612
assert span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT] == "2"
613-
assert span.attributes["langfuse.observation.metadata.finish_reason"] == "stop"
613+
assert span.attributes["langfuse.observation.metadata.finish_reason"] == '"stop"'
614614
assert json_attr(span, LangfuseOtelSpanAttributes.OBSERVATION_USAGE_DETAILS) == {
615615
"prompt_tokens": 3,
616616
"completion_tokens": 1,
@@ -734,7 +734,7 @@ async def test_openai_async_stream_preserves_original_stream_contract(
734734
span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_COMPLETION_START_TIME]
735735
is not None
736736
)
737-
assert span.attributes["langfuse.observation.metadata.finish_reason"] == "stop"
737+
assert span.attributes["langfuse.observation.metadata.finish_reason"] == '"stop"'
738738
assert json_attr(span, LangfuseOtelSpanAttributes.OBSERVATION_USAGE_DETAILS) == {
739739
"prompt_tokens": 3,
740740
"completion_tokens": 1,
@@ -777,7 +777,7 @@ async def test_openai_async_stream_supports_anext(
777777
span.attributes[LangfuseOtelSpanAttributes.OBSERVATION_COMPLETION_START_TIME]
778778
is not None
779779
)
780-
assert span.attributes["langfuse.observation.metadata.finish_reason"] == "stop"
780+
assert span.attributes["langfuse.observation.metadata.finish_reason"] == '"stop"'
781781
assert json_attr(span, LangfuseOtelSpanAttributes.OBSERVATION_USAGE_DETAILS) == {
782782
"prompt_tokens": 3,
783783
"completion_tokens": 1,

‎tests/unit/test_otel.py‎

Lines changed: 107 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -418,7 +418,7 @@ def test_span_attributes(self, langfuse_client, memory_exporter):
418418
# Verify attribute values
419419
assert input_data == {"prompt": "Test prompt"}
420420
assert output_data == {"response": "Updated response"}
421-
assert metadata_data == "test-session"
421+
assert metadata_data == '"test-session"'
422422
assert attributes[LangfuseOtelSpanAttributes.OBSERVATION_LEVEL] == "INFO"
423423
assert (
424424
attributes[LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]
@@ -614,7 +614,7 @@ def test_complex_scenario(self, langfuse_client, memory_exporter):
614614
proc_metadata = proc["attributes"][
615615
f"{LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.step"
616616
]
617-
assert proc_metadata == "processing"
617+
assert proc_metadata == '"processing"'
618618

619619
# Parse input/output JSON
620620
llm_input = json.loads(
@@ -1574,11 +1574,11 @@ def test_complex_metadata_serialization(self):
15741574
)
15751575
assert (
15761576
simple_result[f"{LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.key1"]
1577-
== "value1"
1577+
== '"value1"'
15781578
)
15791579
assert (
15801580
simple_result[f"{LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.key2"]
1581-
== 123
1581+
== "123"
15821582
)
15831583

15841584
# Test case 3: Nested dict (will be flattened in current implementation)
@@ -1631,7 +1631,7 @@ def test_complex_metadata_serialization(self):
16311631

16321632
# The nested structures are serialized as JSON strings
16331633
assert json.loads(complex_result[level1_key]) == complex_dict["level1"]
1634-
assert complex_result[sibling_key] == "value"
1634+
assert complex_result[sibling_key] == '"value"'
16351635

16361636
def test_nested_metadata_updates(self):
16371637
"""Test that nested metadata updates don't overwrite unrelated keys."""
@@ -1986,6 +1986,108 @@ def update_random_metadata(thread_id):
19861986
assert "version" in system_data
19871987
assert "features" in system_data
19881988

1989+
def test_metadata_values_are_json_encoded(self, langfuse_client, memory_exporter):
1990+
"""Every per-key metadata value is sent as a JSON-encoded string."""
1991+
from datetime import timezone
1992+
1993+
prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
1994+
with langfuse_client.start_as_current_observation(
1995+
name="json-metadata-span",
1996+
metadata={
1997+
"string": "hello",
1998+
"numeric_string": "123",
1999+
"bool_string": "true",
2000+
"int": 5,
2001+
"bool": True,
2002+
"float": 1.5,
2003+
"big_int": 2**70,
2004+
"nan": float("nan"),
2005+
"list": [1, "a", None],
2006+
"nested": {"a": {"b": [1, 2]}, "c": "d"},
2007+
"datetime": datetime(2024, 1, 2, 3, 4, 5, tzinfo=timezone.utc),
2008+
},
2009+
):
2010+
pass
2011+
2012+
attributes = self.get_spans_by_name(memory_exporter, "json-metadata-span")[0][
2013+
"attributes"
2014+
]
2015+
2016+
expected = {
2017+
"string": '"hello"',
2018+
"numeric_string": '"123"',
2019+
"bool_string": '"true"',
2020+
"int": "5",
2021+
"bool": "true",
2022+
"float": "1.5",
2023+
"big_int": '"1180591620717411303424"',
2024+
"nan": '"NaN"',
2025+
"list": '[1, "a", null]',
2026+
"nested": '{"a": {"b": [1, 2]}, "c": "d"}',
2027+
"datetime": '"2024-01-02T03:04:05Z"',
2028+
}
2029+
for key, value in expected.items():
2030+
assert attributes[f"{prefix}.{key}"] == value, key
2031+
2032+
# Decoding restores the original type, so strings and numbers stay distinct.
2033+
assert json.loads(attributes[f"{prefix}.numeric_string"]) == "123"
2034+
assert json.loads(attributes[f"{prefix}.int"]) == 5
2035+
assert json.loads(attributes[f"{prefix}.bool"]) is True
2036+
2037+
def test_big_int_metadata_value_survives_otlp_encoding(
2038+
self, langfuse_client, memory_exporter
2039+
):
2040+
"""Ints beyond int64 must not make the OTLP encoder drop the key."""
2041+
from opentelemetry.exporter.otlp.proto.common.trace_encoder import (
2042+
encode_spans,
2043+
)
2044+
2045+
with langfuse_client.start_as_current_observation(
2046+
name="big-int-span", metadata={"big": 2**70, "small": 1}
2047+
):
2048+
pass
2049+
2050+
spans = [
2051+
s for s in memory_exporter.get_finished_spans() if s.name == "big-int-span"
2052+
]
2053+
request = encode_spans(spans)
2054+
encoded = {
2055+
kv.key: kv.value.string_value
2056+
for kv in request.resource_spans[0].scope_spans[0].spans[0].attributes
2057+
}
2058+
2059+
prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
2060+
assert encoded[f"{prefix}.big"] == '"1180591620717411303424"'
2061+
assert encoded[f"{prefix}.small"] == "1"
2062+
2063+
def test_none_metadata_value_keeps_earlier_value_on_update(
2064+
self, langfuse_client, memory_exporter
2065+
):
2066+
"""None values are skipped, so they don't overwrite earlier keys."""
2067+
prefix = LangfuseOtelSpanAttributes.OBSERVATION_METADATA
2068+
with langfuse_client.start_as_current_observation(
2069+
name="none-metadata-span", metadata={"keep": "first", "other": 1}
2070+
) as span:
2071+
span.update(metadata={"keep": None, "other": 2})
2072+
2073+
attributes = self.get_spans_by_name(memory_exporter, "none-metadata-span")[0][
2074+
"attributes"
2075+
]
2076+
2077+
assert attributes[f"{prefix}.keep"] == '"first"'
2078+
assert attributes[f"{prefix}.other"] == "2"
2079+
2080+
def test_flatten_metadata_trace_prefix_uses_same_encoding(self):
2081+
"""The trace prefix variant encodes values the same way."""
2082+
from langfuse._client.attributes import _flatten_and_serialize_metadata
2083+
2084+
result = _flatten_and_serialize_metadata(
2085+
{"s": "x", "i": 1, "none": None}, "trace"
2086+
)
2087+
2088+
prefix = LangfuseOtelSpanAttributes.TRACE_METADATA
2089+
assert result == {f"{prefix}.s": '"x"', f"{prefix}.i": "1"}
2090+
19892091

19902092
class TestMultiProjectSetup(TestOTelBase):
19912093
"""Tests for multi-project setup within the same process.

‎tests/unit/test_propagate_attributes.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2769,17 +2769,17 @@ def test_experiment_run_metadata_overrides_item_metadata(
27692769
self.verify_span_attribute(
27702770
span,
27712771
f"{LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.shared",
2772-
"run",
2772+
'"run"',
27732773
)
27742774
self.verify_span_attribute(
27752775
span,
27762776
f"{LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.experiment_run_name",
2777-
"run-name",
2777+
'"run-name"',
27782778
)
27792779
self.verify_span_attribute(
27802780
span,
27812781
f"{LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.item_only",
2782-
"yes",
2782+
'"yes"',
27832783
)
27842784

27852785
def test_experiment_attributes_propagate_with_dataset(

0 commit comments

Comments
 (0)