fix(langchain): propagate trace name metadata

[hassiebp]

Summary

• propagate langfuse_trace_name from LangChain root metadata into propagate_attributes() so root and child spans receive langfuse.trace.name
• strip langfuse_trace_name from observation metadata once it is treated as a trace-level attribute
• add regression coverage for both metadata-based trace-name propagation and root chain export when on_chain_end runs in a copied async context

Verification

• uv run --frozen pytest tests/unit/test_langchain.py -q
• uv run --frozen ruff check langfuse/langchain/CallbackHandler.py tests/unit/test_langchain.py

Closes #13023
Refs LFE-9178

Disclaimer: Experimental PR review

Greptile Summary

This PR adds langfuse_trace_name to the set of root-chain trace attributes that are extracted from LangChain metadata and propagated to all spans via propagate_attributes(), and strips the key from raw observation metadata to avoid it leaking as a raw metadata entry. Two regression tests are added: one for the metadata-based trace-name propagation across root and child spans, and one for the scenario where on_chain_end fires in a copied async context.

Confidence Score: 5/5

Safe to merge — changes are additive, well-scoped, and covered by targeted regression tests.

All three change sites (attribute extraction, propagation call, strip list) are consistent with existing patterns for langfuse_user_id/langfuse_session_id. No pre-existing logic is altered, double-exit of the propagation context manager is guarded by the null check in _exit_propagation_context, and both new code paths are covered by new tests. No P0/P1 findings.

No files require special attention.

Important Files Changed

Filename	Overview
langfuse/langchain/CallbackHandler.py	Adds langfuse_trace_name extraction in _parse_langfuse_trace_attributes, passes trace_name to propagate_attributes() at root chain start, and adds the key to langfuse_trace_attribute_keys so it is stripped from raw observation metadata for all spans.
tests/unit/test_langchain.py	Adds two regression tests: one verifying TRACE_NAME attribute is set on root and child spans and langfuse_trace_name is stripped from root-span metadata, and one verifying correct export when on_chain_end runs in a copied async context.

Sequence Diagram

sequenceDiagram
    participant LC as LangChain Runtime
    participant CB as CallbackHandler
    participant PA as propagate_attributes()
    participant CS as Child Spans

    LC->>CB: on_chain_start(metadata={langfuse_trace_name: my-trace}, parent_run_id=None)
    CB->>CB: _parse_langfuse_trace_attributes() extracts trace_name
    CB->>PA: propagate_attributes(trace_name=my-trace, ...)
    PA-->>CB: context manager entered (sets langfuse.trace.name on active span)
    CB->>CB: start_observation() with metadata stripped of langfuse_trace_name
    LC->>CB: on_chain_start(metadata={langfuse_trace_name: my-trace}, parent_run_id=id)
    CB->>CS: start_observation() — inherits langfuse.trace.name via OTel context
    LC->>CB: on_chain_end(run_id=root)
    CB->>PA: __exit__() — propagation context torn down

Loading

_{Reviews (1): Last reviewed commit: "fix(langchain): propagate trace name met..." | Re-trigger Greptile}

[github-actions]

@claude review