Skip to content

Commit 8d7c066

Browse files
feat(tracing)!: JSON-serialize propagated metadata values (#1932)
* chore!: require Python 3.11 or newer Python 3.10 reaches end of life in October 2026. Raise requires-python to >=3.11, target py311 in ruff, drop 3.10 from the CI unit matrix, and remove the pre-3.11 fallbacks for asyncio.create_task(context=...) and typing.NotRequired. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * feat(openai)!: drop support for OpenAI SDK versions below 1.0 The OpenAI integration now always uses the v1 client shapes. Remove the pre-1.0 method definitions and every _is_openai_v1() branch, and raise the dev dependency floor to openai>=1.0.0. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * feat(otel)!: send x-langfuse-ingestion-version: 4 by default The default OTLP exporter now sends x-langfuse-ingestion-version: 4 so servers in dual-write or preview mode process exported spans directly. It is a no-op on events_only deployments, and additional_headers can still override it. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * feat(client)!: remove blocked_instrumentation_scopes blocked_instrumentation_scopes was deprecated in favor of should_export_span. Remove it from Langfuse, the resource manager and the span processor, and drop the leftover is_active entry from the create_prompt docstring. LANGFUSE_HOST and host keep working, but now log a deprecation warning when they decide the base URL. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * feat(tracing)!: JSON-serialize propagated metadata values propagate_attributes(metadata=...) coerced non-string values with str(), so a boolean became "True" and a list became its Python repr. Serialize them as JSON instead, like observation metadata, and drop None values instead of sending "None". Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * fix(tracing): serialize propagated metadata like JSON.stringify Use compact separators, keep non-ASCII characters, and send None as "null", so the Python and JS SDKs emit byte-identical propagated metadata values. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * fix(observe): keep detecting legacy-marked coroutine functions inspect.iscoroutinefunction ignores asyncio's _is_coroutine marker, which asgiref's markcoroutinefunction sets on Python < 3.12. Accept both so such functions keep the async wrapper and their observation ends after the coroutine runs. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * test(otel): pin that a mixed-case ingestion-version override wins Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * fix(tracing): keep the exact digits of large integer metadata values Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * fix(tracing): match JS for nested big ints and non-finite metadata Integers keep their exact digits as JSON numbers at any depth, and propagated metadata values containing NaN or Infinity are dropped with a warning instead of being stored, matching the JS SDK. Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> * feat(client): keep host and LANGFUSE_HOST working without a warning Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
1 parent 049a6da commit 8d7c066

2 files changed

Lines changed: 146 additions & 9 deletions

File tree

‎langfuse/_client/propagation.py‎

Lines changed: 56 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
propagate to all child spans within the context.
66
"""
77

8+
import math
89
import re
910
from typing import (
1011
Any,
@@ -40,6 +41,7 @@
4041

4142
from langfuse._client.attributes import LangfuseOtelSpanAttributes
4243
from langfuse._client.constants import LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT
44+
from langfuse._utils.serializer import EventSerializer
4345
from langfuse.logger import langfuse_logger
4446
from langfuse.model import PromptClient
4547

@@ -281,8 +283,11 @@ def propagate_attributes(
281283
- **Validation**: Attribute values (user_id, session_id, version, tags,
282284
trace_name) must be strings ≤200 characters. Environment must also match
283285
Langfuse's environment format: lowercase alphanumeric with optional
284-
hyphens or underscores, must be ≤40 characters, and it must not start with "langfuse". Metadata
285-
values are coerced to strings before the 200 character limit is applied.
286+
hyphens or underscores, must be ≤40 characters, and it must not start with "langfuse". Non-string
287+
metadata values are serialized like JavaScript's `JSON.stringify`
288+
(compact separators, non-ASCII kept as is, None becomes "null",
289+
integers keep their exact digits) before the 200 character limit is
290+
applied. Values containing NaN or Infinity are dropped.
286291
Invalid values will be dropped with a warning logged.
287292
- **OpenTelemetry**: This uses OpenTelemetry context propagation under the hood,
288293
making it compatible with other OTel-instrumented libraries.
@@ -393,10 +398,21 @@ def _propagate_attributes(
393398
validated_metadata: Dict[str, str] = {}
394399

395400
for key, value in metadata_value.items():
396-
coerced_value = value if isinstance(value, str) else str(value)
401+
serialized_value = _serialize_propagated_metadata_value(value)
402+
403+
if serialized_value is None:
404+
langfuse_logger.warning(
405+
"Propagated attribute '%s.%s' contains NaN or Infinity, which "
406+
"is not valid JSON. Dropping value.",
407+
metadata_key,
408+
key,
409+
)
410+
continue
397411

398-
if _validate_string_value(value=coerced_value, key=f"{metadata_key}.{key}"):
399-
validated_metadata[key] = coerced_value
412+
if _validate_string_value(
413+
value=serialized_value, key=f"{metadata_key}.{key}"
414+
):
415+
validated_metadata[key] = serialized_value
400416

401417
if validated_metadata:
402418
context = _set_propagated_attribute(
@@ -641,6 +657,41 @@ def _validate_propagated_value(
641657
return value
642658

643659

660+
class _PropagatedMetadataSerializer(EventSerializer):
661+
"""EventSerializer variant that matches the JS SDK for propagated metadata.
662+
663+
Integers keep their exact digits as JSON numbers at any depth, and values
664+
containing NaN or Infinity are flagged so the caller can drop them.
665+
"""
666+
667+
def __init__(self, *args: Any, **kwargs: Any) -> None:
668+
super().__init__(*args, **kwargs)
669+
self.found_non_finite_number = False
670+
671+
def default(self, obj: Any) -> Any:
672+
if isinstance(obj, int) and not isinstance(obj, bool):
673+
return obj
674+
675+
if isinstance(obj, float) and not math.isfinite(obj):
676+
self.found_non_finite_number = True
677+
return None
678+
679+
return super().default(obj)
680+
681+
682+
def _serialize_propagated_metadata_value(value: Any) -> Optional[str]:
683+
"""Serialize like JSON.stringify in the JS SDK; None means drop the value."""
684+
if isinstance(value, str):
685+
return value
686+
687+
serializer = _PropagatedMetadataSerializer(
688+
separators=(",", ":"), ensure_ascii=False
689+
)
690+
serialized = serializer.encode(value)
691+
692+
return None if serializer.found_non_finite_number else serialized
693+
694+
644695
def _validate_string_value(*, value: str, key: str) -> bool:
645696
if not isinstance(value, str):
646697
langfuse_logger.warning( # type: ignore

‎tests/unit/test_propagate_attributes.py‎

Lines changed: 90 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -461,17 +461,34 @@ def test_non_string_user_id_dropped(self, langfuse_client, memory_exporter):
461461
child_span, LangfuseOtelSpanAttributes.TRACE_USER_ID
462462
)
463463

464-
def test_non_string_metadata_values_coerced(
464+
def test_non_string_metadata_values_json_serialized(
465465
self, langfuse_client, memory_exporter, caplog
466466
):
467-
"""Verify non-string metadata values are coerced instead of dropped."""
467+
"""Verify non-string metadata values are JSON-serialized instead of dropped."""
468468

469469
caplog.set_level("WARNING", logger="langfuse")
470470
metadata = {
471471
"langgraph_step": 1,
472472
"langgraph_triggers": ["branch:agent"],
473473
"langgraph_path": ("root", "agent"),
474474
"max_search_results": 5,
475+
"is_cached": True,
476+
"ratio": 0.5,
477+
"config": {"model": "gpt-4o", "nested": {"b": [1, None], "a": "ü"}},
478+
"label": ["Läufe", "🚀"],
479+
"empty": None,
480+
}
481+
# Byte-identical to JSON.stringify in the JS SDK for the same values.
482+
expected = {
483+
"langgraph_step": "1",
484+
"langgraph_triggers": '["branch:agent"]',
485+
"langgraph_path": '["root","agent"]',
486+
"max_search_results": "5",
487+
"is_cached": "true",
488+
"ratio": "0.5",
489+
"config": '{"model":"gpt-4o","nested":{"b":[1,null],"a":"ü"}}',
490+
"label": '["Läufe","🚀"]',
491+
"empty": "null",
475492
}
476493

477494
with langfuse_client.start_as_current_observation(name="parent-span"):
@@ -481,15 +498,84 @@ def test_non_string_metadata_values_coerced(
481498

482499
child_span = self.get_span_by_name(memory_exporter, "child-span")
483500

484-
for key, value in metadata.items():
501+
for key, value in expected.items():
485502
self.verify_span_attribute(
486503
child_span,
487504
f"{LangfuseOtelSpanAttributes.TRACE_METADATA}.{key}",
488-
str(value),
505+
value,
489506
)
490507

491508
assert "value is not a string. Dropping value." not in caplog.text
492509

510+
def test_large_integer_metadata_keeps_its_digits(
511+
self, langfuse_client, memory_exporter
512+
):
513+
"""Verify integers beyond JS's safe range are sent as plain digits."""
514+
with langfuse_client.start_as_current_observation(name="parent-span"):
515+
with propagate_attributes(metadata={"snowflake_id": 9007199254740993}):
516+
child = langfuse_client.start_observation(name="child-span")
517+
child.end()
518+
519+
child_span = self.get_span_by_name(memory_exporter, "child-span")
520+
self.verify_span_attribute(
521+
child_span,
522+
f"{LangfuseOtelSpanAttributes.TRACE_METADATA}.snowflake_id",
523+
"9007199254740993",
524+
)
525+
526+
def test_nested_large_integer_metadata_keeps_its_digits(
527+
self, langfuse_client, memory_exporter
528+
):
529+
"""Verify nested integers beyond JS's safe range stay unquoted digits."""
530+
with langfuse_client.start_as_current_observation(name="parent-span"):
531+
with propagate_attributes(
532+
metadata={
533+
"ids": [9007199254740993, 1],
534+
"ref": {"snowflake_id": 9007199254740993},
535+
}
536+
):
537+
child = langfuse_client.start_observation(name="child-span")
538+
child.end()
539+
540+
child_span = self.get_span_by_name(memory_exporter, "child-span")
541+
self.verify_span_attribute(
542+
child_span,
543+
f"{LangfuseOtelSpanAttributes.TRACE_METADATA}.ids",
544+
"[9007199254740993,1]",
545+
)
546+
self.verify_span_attribute(
547+
child_span,
548+
f"{LangfuseOtelSpanAttributes.TRACE_METADATA}.ref",
549+
'{"snowflake_id":9007199254740993}',
550+
)
551+
552+
def test_non_finite_number_metadata_is_dropped(
553+
self, langfuse_client, memory_exporter, caplog
554+
):
555+
"""Verify values containing NaN or Infinity are dropped, like in the JS SDK."""
556+
caplog.set_level("WARNING", logger="langfuse")
557+
with langfuse_client.start_as_current_observation(name="parent-span"):
558+
with propagate_attributes(
559+
metadata={
560+
"kept": 1.5,
561+
"nan": float("nan"),
562+
"inf": float("-inf"),
563+
"nested": {"scores": [1.0, float("inf")]},
564+
}
565+
):
566+
child = langfuse_client.start_observation(name="child-span")
567+
child.end()
568+
569+
child_span = self.get_span_by_name(memory_exporter, "child-span")
570+
self.verify_span_attribute(
571+
child_span, f"{LangfuseOtelSpanAttributes.TRACE_METADATA}.kept", "1.5"
572+
)
573+
for key in ("nan", "inf", "nested"):
574+
self.verify_missing_attribute(
575+
child_span, f"{LangfuseOtelSpanAttributes.TRACE_METADATA}.{key}"
576+
)
577+
assert "metadata.nan" in caplog.text
578+
493579
def test_mixed_valid_invalid_metadata(self, langfuse_client, memory_exporter):
494580
"""Verify mixed valid/invalid metadata - valid entries kept, invalid dropped."""
495581
with langfuse_client.start_as_current_observation(name="parent-span"):

0 commit comments

Comments
 (0)