Debugging LangChain Applications

When inspecting a simple Jupyter notebook that uses LangChain, the typical flow is:

Define a prompt.
Create an LLM instance.
Wrap both in a chain.
Invoke the chain with inputs.

This guide provides a concise, corrected example showing the pattern, how to enable global debug logging in LangChain, and how to interpret the runtime logs to diagnose issues, measure latency, and inspect intermediate prompts.

Quick example: a minimal Chat LLM chain

The example below demonstrates a minimal ChatOpenAI + ChatPromptTemplate + LLMChain setup. Note the updated import paths that match common LangChain usage.

from langchain.chat_models import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.chains import LLMChain

prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a {subject} teacher"),
        ("human", "Tell me about {concept}")
    ]
)

llm = ChatOpenAI()  # configure with api_key or environment variables as needed
chain = LLMChain(llm=llm, prompt=prompt)

result = chain.invoke({"subject": "physics", "concept": "galaxy"})
print(result)

Typical chain output

A typical returned result (dictionary) contains the inputs and the generated text. Example:

{
  "subject": "physics",
  "concept": "galaxy",
  "text": "A galaxy is a gravitationally bound system of stars, stellar remnants, interstellar gas, dust, dark matter, and other astronomical objects. Galaxies can vary greatly in size and shape, from small dwarf galaxies with only a few billion stars to massive galaxies with trillions of stars. Our own galaxy, the Milky Way, is a barred spiral galaxy that contains roughly 100–400 billion stars. Galaxies are classified into spiral, elliptical, and irregular types. They are organized into larger structures such as galaxy clusters and superclusters. Studying galaxies helps us understand the evolution and dynamics of the cosmos."
}

Why enable LangChain debug logging?

As chains grow in complexity—multiple components, custom transforms, callbacks, or several LLM calls—it’s easy to lose visibility into what happened during execution. LangChain provides a global debug flag that instruments runs and prints structured, per-component logs showing inputs, prompts, outputs, and timing. This visibility helps you:

Diagnose unexpected outputs or logic errors.
Inspect intermediate prompts and transformed inputs.
Measure token usage and per-component latency.
Identify which component produced an error or unexpected text.

Enabling global debug logging

Turn on global debug tracing with:

from langchain.globals import set_debug
set_debug(True)

Below is a full example that enables debug and runs the same chain:

from langchain.chat_models import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain.chains import LLMChain
from langchain.globals import set_debug

set_debug(True)

prompt = ChatPromptTemplate.from_messages(
    [
        ("system", "You are a {subject} teacher"),
        ("human", "Tell me about {concept}")
    ]
)

llm = ChatOpenAI()
chain = LLMChain(llm=llm, prompt=prompt)

chain.invoke({"subject": "physics", "concept": "galaxy"})

Sample debug output (abridged)

When debug is enabled, LangChain prints a structured trace. The example below is normalized for clarity:

[chain/start] [1:chain:LLMChain] Entering Chain run with input:
{
  "subject": "physics",
  "concept": "galaxy"
}
[llm/start] [1:chain:LLMChain > 2:llm:ChatOpenAI] Entering LLM run with input:
{
  "prompts": [
    "System: You are a physics teacher\nHuman: Tell me about galaxy"
  ]
}
[llm/end]   [1:chain:LLMChain > 2:llm:ChatOpenAI] [3.27s] Exiting LLM run with output:
{
  "generations": [
    {
      "text": "Galaxies are vast systems of stars, dust, gas, and dark matter held together by gravity. They come in various shapes and sizes..."
    }
  ]
}
[chain/end] [1:chain:LLMChain] [3.27s] Exiting Chain run with output:
{
  "text": "Galaxies are vast systems of stars, dust, gas, and dark matter held together by gravity. They come in various shapes and sizes, ranging from small dwarf galaxies with just a few billion stars to massive galaxies like the Milky Way, which contains hundreds of billions of stars.\n\nGalaxies are the building blocks of the universe and are spread throughout the cosmos. They can be classified into different types based on their shape, such as spiral galaxies, elliptical galaxies, and irregular galaxies.\n\nStudying galaxies helps us understand the evolution of the universe, the formation of stars and planetary systems, and the distribution of dark matter."
}

Interpreting the debug tags

Use the following as a quick reference to the most common log tags:

Log tag	What it indicates	Example information
`chain/start`	Chain run began	Inputs to the chain (e.g., `subject`, `concept`)
`llm/start`	An LLM component was invoked	Exact prompt(s) sent to the model
`llm/end`	LLM returned	Generated text, `generations` arrays
`chain/end`	Chain finished	Final chain output and any aggregated metadata
Timing (e.g., `[3.27s]`)	Duration for the component	Per-component latency, useful for bottlenecks

Example LLM output metadata

The LLM output and the chain run often include metadata such as token usage and model identification. Example:

{
  "llm_output": {
    "token_usage": {
      "completion_tokens": 202,
      "prompt_tokens": 20,
      "total_tokens": 222
    },
    "model_name": "gpt-3.5-turbo",
    "system_fingerprint": "fp_4f0b692a78"
  },
  "run": null
}

When to enable debug logs

During development and troubleshooting.
When iterating on prompt engineering and wanting to inspect the exact prompt(s) sent.
To measure token usage and latency for cost/optimization decisions.
While building or validating multi-component chains to see intermediate inputs/outputs.

Enable set_debug(True) while developing or troubleshooting chains to obtain a detailed execution trace of each component. Debug logs may contain sensitive data—do not enable them in production or when handling private data.

Links and references

If you need help interpreting a specific debug trace or want assistance instrumenting more complex multi-component chains (callbacks, transforms, or retrievers), share the trace and chain configuration and we can walk through it step by step.

Introduction

Overview of LangChain

Key Components of LangChain

Interacting with LLMs

Tips, Tricks, and Resources

Introduction to LCEL

Adding Memory to LLM Apps

Performing Retrieval

Implementing Chains

Using Tools

Building Agents

Conclusion

Building Blocks of LLM Apps

Debugging LangChain Applications

Quick example: a minimal Chat LLM chain

Typical chain output

Why enable LangChain debug logging?

Enabling global debug logging

Sample debug output (abridged)

Interpreting the debug tags

Example LLM output metadata

When to enable debug logs

Links and references

Watch Video

​Quick example: a minimal Chat LLM chain

​Typical chain output

​Why enable LangChain debug logging?

​Enabling global debug logging

​Sample debug output (abridged)

​Interpreting the debug tags

​Example LLM output metadata

​When to enable debug logs

​Links and references

Watch Video

Quick example: a minimal Chat LLM chain

Typical chain output

Why enable LangChain debug logging?

Enabling global debug logging

Sample debug output (abridged)

Interpreting the debug tags

Example LLM output metadata

When to enable debug logs

Links and references