feat(langchain): allow injecting trace_context into LangchainCallbackHandler (#1419)

[hassiebp]

Important

Add trace_context parameter to LangchainCallbackHandler to enhance tracing capabilities in CallbackHandler.py.

• Feature:
  • Add trace_context parameter to LangchainCallbackHandler constructor in CallbackHandler.py.
  • Utilize trace_context in on_chain_start() when obs is an instance of Langfuse.
• Imports:
  • Import TraceContext from langfuse.types.

^{This description was created by for da8e1be. You can customize this summary. It will automatically update as commits are pushed.}

Disclaimer: Experimental PR review

Greptile Overview

Greptile Summary

Added trace_context parameter to LangchainCallbackHandler, allowing users to inject external trace context (trace_id and optional parent_span_id) into the handler. This enables integrating Langchain traces with external tracing systems.

• Added trace_context: Optional[TraceContext] parameter to __init__
• In on_chain_start, when the parent is the Langfuse client, trace_context is passed to start_observation
• Issue: trace_context is only applied in on_chain_start. Standalone LLM calls, tool calls, and retriever calls that occur without a parent chain will not have the trace_context applied, as on_tool_start, on_retriever_start, and __on_llm_action do not pass trace_context even when the parent observation is the Langfuse client.

Confidence Score: 3/5

• Feature works for chains but has incomplete coverage for standalone LLM/tool/retriever calls
• The core feature works correctly for chain-based invocations, but trace_context is not applied consistently across all entry points (tool, retriever, LLM). This limits the feature's usefulness when Langchain components are invoked directly without a chain wrapper.
• langfuse/langchain/CallbackHandler.py - on_tool_start, on_retriever_start, and __on_llm_action should also pass trace_context when the parent observation is the Langfuse client

Important Files Changed

File Analysis

Filename	Score	Overview
langfuse/langchain/CallbackHandler.py	3/5	Added trace_context parameter to LangchainCallbackHandler allowing users to inject trace context, but only applies to on_chain_start - standalone LLM/tool/retriever calls don't pass trace_context.

Sequence Diagram

sequenceDiagram
    participant User
    participant LangchainCallbackHandler
    participant Langfuse
    participant LangfuseSpan

    User->>LangchainCallbackHandler: __init__(trace_context)
    Note right of LangchainCallbackHandler: stores self.trace_context

    alt Chain Start (root level)
        User->>LangchainCallbackHandler: on_chain_start(parent_run_id=None)
        LangchainCallbackHandler->>LangchainCallbackHandler: _get_parent_observation()
        Note right of LangchainCallbackHandler: returns Langfuse client
        LangchainCallbackHandler->>Langfuse: start_observation(trace_context=✓)
        Langfuse-->>LangchainCallbackHandler: LangfuseSpan
    end

    alt Tool/LLM/Retriever Start (root level)
        User->>LangchainCallbackHandler: on_tool_start(parent_run_id=None)
        LangchainCallbackHandler->>LangchainCallbackHandler: _get_parent_observation()
        Note right of LangchainCallbackHandler: returns Langfuse client
        LangchainCallbackHandler->>Langfuse: start_observation(trace_context=✗)
        Note right of Langfuse: trace_context NOT passed!
        Langfuse-->>LangchainCallbackHandler: LangfuseSpan
    end

Loading

[greptile-apps]

Additional Comments (1)

1. langfuse/langchain/CallbackHandler.py, line 670-676 (link)

   logic: trace_context not passed for standalone tool invocations. When parent_run_id is None (root-level), _get_parent_observation returns the Langfuse client, but trace_context is not passed here, unlike in on_chain_start. Similar issue exists in on_retriever_start and __on_llm_action.

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}