fix(tracing): serialize non-string propagated metadata as JSON

[niklassemmler]

Sibling of #1944 (LFE-17153). #1944 moves observation metadata to one JSON attribute and leaves propagated trace metadata per-key. This PR fixes how the per-key trace metadata values are encoded.

Problem

propagate_attributes(metadata=...) coerces non-string values with str() (propagation.py). The server stores per-key trace metadata (langfuse.trace.metadata.<key>) as the raw string without parsing it, so Python reprs end up in storage:

Value	Stored before	Stored after
["branch:agent"]	['branch:agent']	["branch:agent"]
("root", "agent")	('root', 'agent')	["root","agent"]
{"model": "gpt-4"}	{'model': 'gpt-4'}	{"model":"gpt-4"}
True	True	true
datetime(2024, 1, 1, tzinfo=utc)	2024-01-01 00:00:00+00:00	"2024-01-01T00:00:00Z"
None	None	(skipped)
1, 0.5, "text"	1, 0.5, text	unchanged

This hits LangChain/LangGraph users in particular: the callback handler forwards run metadata such as langgraph_triggers and langgraph_path to propagate_attributes.

Change

• Non-string values are serialized as compact JSON with EventSerializer (same serializer and separators as observation metadata in feat(tracing)!: send observation metadata as one JSON attribute #1944). Strings are kept as they are.
• None values are skipped instead of being stored as "None", matching how observation metadata treats None.
• The 200 character limit still applies, now to the serialized value.

Behavior change to call out

Stored values change for non-string trace metadata (see table). Saved filters on the old repr values (e.g. enabled = True, langgraph_triggers = ['branch:agent']) won't match new data. Strings and numbers, the common case, are unchanged. This ships as fix, but it could ride along with the #1944 major if reviewers prefer to group stored-value changes.

Parity with langfuse-js

JS propagateAttributes takes Record<string, string> and drops non-string values with a warning. Python keeps coercing on purpose: test_non_string_metadata_values_coerced pins coercion for LangGraph keys. This PR doesn't change that decision, it only makes the coerced value valid JSON. Whether both SDKs should coerce to JSON or both drop non-strings is an open question for the metadata workstream.

Verification

• uv run --frozen ruff check . ✅
• uv run --frozen ruff format ✅
• uv run --frozen mypy langfuse --no-error-summary ✅
• Wrote the tests first and confirmed they failed on current code (Expected ... ["branch:agent"], got ['branch:agent'], and None stored as an attribute).
• uv run --frozen pytest -n auto --dist worksteal tests/unit --deselect tests/unit/test_prompt.py: 690 passed ✅
• tests/unit/test_prompt.py: 18 errors, same on main (Langfuse client is not initialized, a local env issue).
• tests/e2e: not run, no Langfuse server available.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge with its explicitly acknowledged stored-value changes.

What we checked:

• Bad metadata stops tracing: EventSerializer catches encoding errors and returns a fallback string. Its depth limit also bounds circular collections.
• New import prevents startup: propagation.py already imports attributes.py, which imports EventSerializer. The new direct import does not add a module to that path.

Summary

Changes propagate_attributes to serialize non-string metadata as compact JSON, leave strings unchanged, and skip None.

• Keeps the 200-character limit after serialization.
• Adds tests for common value types, skipped values, and oversized JSON.
• No actionable issues found.
• Author niklassemmler explicitly acknowledges that saved filters using old Python representations will not match newly encoded values. This stored-value change is intentional.

_{Reviews (1) · Last reviewed commit: "fix(tracing): serialize non-string propa..." · Reviewed by Greptile}

[github-actions]

@claude review

[claude]

Claude Code Review

No review was started: this request came from a bot account. Manual reviews can only be requested by someone with write access to this repository. Ask a maintainer to comment @claude review, or have your automation post the comment from a user account with write access.

_{Tip: disable this comment in your organization's Code Review settings.}

[niklassemmler]

@claude review

🤖 Written by Claude (an AI agent) on behalf of Niklas

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[niklassemmler]

Closing in favor of #1932, which JSON-serializes propagated metadata values on prepare-v5-release (it also keeps exact integer digits and drops NaN/Infinity). Changing how stored metadata values look is a breaking change, so it ships with v5 rather than in a v4 minor release.