LangChain - Lemma

LangChain chains and agents emit spans through Langfuse’s callback handler. Add the handler, point Langfuse at Lemma, and wrap each run in one root span so chains, model calls, and tool calls become a single nested trace. Use the Langfuse LangChain integration as the reference.

One agent execution = one trace. Wrap the run in a single root span so every model and tool call nests under it. See the trace contract.

LangChain traces render fully in Lemma today. Automated issue detection is being expanded to this shape — see Good trace vs bad trace for current status.

Recipe

Install

Python
TypeScript

pip install langchain langchain-openai langfuse opentelemetry-sdk opentelemetry-exporter-otlp

npm install langchain @langchain/openai @langfuse/langchain @langfuse/otel @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-proto

Python
TypeScript

# instrumentation.py — imported first, before your app code
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint=os.environ["LEMMA_BASE_URL"],
            headers={
                "Authorization": f"Bearer {os.environ['LEMMA_API_KEY']}",
                "X-Lemma-Project-ID": os.environ["LEMMA_PROJECT_ID"],
            },
        )
    )
)
trace.set_tracer_provider(provider)

// instrumentation.ts — imported first, before your app code
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

export const lemmaProcessor = new LangfuseSpanProcessor({
  exporter: new OTLPTraceExporter({
    url: process.env.LEMMA_BASE_URL,
    headers: {
      Authorization: `Bearer ${process.env.LEMMA_API_KEY}`,
      "X-Lemma-Project-ID": process.env.LEMMA_PROJECT_ID,
    },
  }),
});

new NodeTracerProvider({ spanProcessors: [lemmaProcessor] }).register();

Set the environment variables. Lemma-only export needs no LANGFUSE_* credentials.

export LEMMA_BASE_URL="https://api.uselemma.ai/otel/v1/traces"
export LEMMA_API_KEY="lma_..."
export LEMMA_PROJECT_ID="proj_..."

Add the Langfuse callback handler

Pass Langfuse’s CallbackHandler to your chain or agent so its model and tool calls are captured as spans.

Python
TypeScript

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

import { CallbackHandler } from "@langfuse/langchain";

const langfuseHandler = new CallbackHandler();

Wrap the whole run in one root span

Wrap the chain invocation in a single root span and pass the handler in the call config. Every LangChain span then nests under one trace. Record the input and final output on the root, and set a stable agent name.

Python
TypeScript

from langfuse import get_client

langfuse = get_client()

def run_support_agent(user_message: str, thread_id: str) -> str:
    with langfuse.start_as_current_span(name="support-agent") as root:
        root.update(input=user_message)
        langfuse.update_current_trace(
            name="support-agent",
            session_id=thread_id,
            metadata={"gen_ai.agent.name": "support-agent"},
        )

        result = chain.invoke(
            {"input": user_message},
            config={"callbacks": [langfuse_handler]},
        )

        root.update(output=result)
        return result

import { propagateAttributes, startActiveObservation } from "@langfuse/tracing";

export async function runSupportAgent(userMessage: string, threadId: string) {
  return await startActiveObservation("support-agent", async (root) => {
    root.update({ input: userMessage });

    return await propagateAttributes(
      {
        traceName: "support-agent",
        sessionId: threadId,
        metadata: { "gen_ai.agent.name": "support-agent" },
      },
      async () => {
        const result = await chain.invoke(
          { input: userMessage },
          { callbacks: [langfuseHandler] },
        );

        root.update({ output: result });
        return result;
      },
    );
  });
}

The LangChain spans created inside the callback become children of the root, producing one nested trace:

support-agent              ← trace root (input, output)
├─ ChatOpenAI              ← generation (model, tokens)
├─ search_docs             ← tool call (args, result)
└─ ChatOpenAI              ← generation (final answer)

Flush before the process exits

In short-lived runtimes, flush so the whole trace ships in one batch.

Python
TypeScript

from langfuse import get_client

get_client().flush()

import { lemmaProcessor } from "./instrumentation";

await lemmaProcessor.forceFlush();

If chain steps show up as their own separate traces, the chain ran outside the root’s active context. Keep chain.invoke inside the root span and pass the handler on every call. See Troubleshooting.

Verify in Lemma

Open the Lemma dashboard → Traces and confirm:

One trace per run — a full chain or agent run is one trace, not one per model call.
Root has input and output — the root span shows the user message and the final response.
Generations are nested — each model call appears as a child generation with model and token usage.
Tools are nested — each tool invocation appears as a child tool span with arguments and result.

Next steps

Trace contract

The exact shape Lemma reads.

Setup

Wire the Langfuse → Lemma exporter.

Threads and sessions

Group multi-turn conversations with a thread id.

Good vs bad traces

What issue detection looks for, per shape.

​Recipe

​Verify in Lemma

​Next steps

Trace contract

Setup

Threads and sessions

Good vs bad traces

Recipe

Verify in Lemma

Next steps