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.

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.

Debugging

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()

Getting Started

Platform

Instrumentation

Integrations

Connections

TypeScript

Python

What Lemma records

Debugging

​TypeScript

​Python

​What Lemma records

​Debugging

TypeScript

Python

What Lemma records

Debugging