> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging LangChain Applications

> Guide to enabling and interpreting LangChain global debug logging, with minimal chain example, sample logs, and tips for diagnosing, measuring latency, and inspecting prompts.

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

1. Define a prompt.
2. Create an LLM instance.
3. Wrap both in a chain.
4. 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.

```python theme={null}
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:

```json theme={null}
{
  "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:

```python theme={null}
from langchain.globals import set_debug
set_debug(True)
```

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

```python theme={null}
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:

```plaintext theme={null}
[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:

```json theme={null}
{
  "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.

<Callout icon="lightbulb" color="#1CB2FE">
  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.
</Callout>

## Links and references

* [LangChain Python documentation](https://python.langchain.com/en/latest/)
* [Jupyter](https://jupyter.org)
* [OpenAI API (for model configuration and keys)](https://platform.openai.com/)

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.

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/langchain/module/b5f7771a-fdbc-45b1-a786-6c84bb7ffc76/lesson/2306b896-2eb1-409b-84f6-f2c392dbd3c4" />
</CardGroup>