LangChain

Use Lemma’s LangChain integration when your app runs chains, chat models, retrievers, tools, or agents through LangChain callbacks. Each root execution owns one complete Lemma trace: current-turn input, final answer or root error, promoted thread_id / user_id, typed nested generations/tools/spans, and real wall-clock timing. Standalone LLM/tool/retriever callbacks finalize their own owned trace. Missing-parent events never overwrite concurrent trace state. You do not need to wrap LangChain calls in lemma.trace(). Pass the callback handler through LangChain’s callbacks option, then flush() to send the trace. In a long-lived process, open traces that stay idle past open_trace_ttl (default 2 hours) are finalized and sent so handler state cannot grow without bound. Last activity is the latest of the root open time, child ends, and in-flight run starts, so a long agent loop that still emits callbacks is not evicted. The sweep runs from every on_*_start callback at most once per eviction_interval (default 5 minutes). Lemma sends the partial owned trace, the same payload flush() would, rather than dropping abandoned runs. Pass open_trace_ttl=None to disable. A complete docs-chat agent using this integration lives in examples/langchain (TypeScript) and examples/python/langchain (Python). See Runnable examples.

TypeScript

Install LangChain and the Lemma SDK:

npm install @uselemma/tracing @langchain/core @langchain/openai

Pass langChain() as a callback handler:

import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";
import { langChain } from "@uselemma/tracing";

const lemmaHandler = langChain({
  apiKey: process.env.LEMMA_API_KEY,
  projectId: process.env.LEMMA_PROJECT_ID,
  release: process.env.LEMMA_RELEASE,
  agentName: "support-agent",
  threadIdKey: "conversation_id",
  userIdKey: "user_id",
});

const model = new ChatOpenAI({
  model: "gpt-4o",
  callbacks: [lemmaHandler],
});

export async function callAgent(userMessage: string, conversationId: string) {
  const response = await model.invoke([new HumanMessage(userMessage)], {
    metadata: { conversation_id: conversationId },
  });
  await lemmaHandler.flush();
  return response.content;
}

Python

Install the optional extra:

pip install "uselemma-tracing[langchain]" langchain-openai

Pass langchain() as a callback handler:

import os

from langchain_openai import ChatOpenAI
from uselemma_tracing import langchain

lemma_handler = langchain(
    api_key=os.environ["LEMMA_API_KEY"],
    project_id=os.environ["LEMMA_PROJECT_ID"],
    agent_name="support-agent",
    thread_id_key="conversation_id",
    user_id_key="user_id",
)
model = ChatOpenAI(model="gpt-4o", callbacks=[lemma_handler])


def call_agent(user_message: str, conversation_id: str):
    response = model.invoke(
        user_message,
        config={"metadata": {"conversation_id": conversation_id}},
    )
    return response.content

What Lemma records

LangChain callback	Lemma record
Root chain / standalone LLM / tool / retriever	One owned Lemma trace with current-turn input, final output or root error, `thread_id` / `user_id`, and wall times
LLM or chat model start/end	Generation with normalized `{ role, content }` history, structured assistant output (incl. tool calls), derived provider/model, timing, parent ID
Tool start/end	Tool call with name, input, output or soft/hard error (never both), timing, parent ID
Retriever start/end	Span with query input, output, timing, and parent ID
Nested chain start/end	Child span preserving LangChain parent run IDs (orphan-safe fallback to root)

Promote identity from configurable metadata/tag keys (threadIdKey / thread_id_key, userIdKey / user_id_key). Defaults also check conversation_id, session_id, and resourceId. Prompts, tool inputs, outputs, model output text, and error messages are always recorded. Redact secrets and sensitive user data before they reach the chain.

Debug this integration

Enable debug mode while developing to confirm that spans arrive live and stay nested under the expected parent:

import { enableDebugMode } from "@uselemma/tracing";

enableDebugMode();

from uselemma_tracing import enable_debug_mode

enable_debug_mode()

Tracing

Integrations

Troubleshooting

Reference

TypeScript

Python

What Lemma records

Debug this integration

​TypeScript

​Python

​What Lemma records

​Debug this integration

TypeScript

Python

What Lemma records

Debug this integration