Skip to main content
LangChain can sometimes feel like a black box—prompts go in, and parsed outputs come out. When you encounter formatting issues or unexpected responses, visibility into each execution step is crucial. This guide covers essential techniques to help you debug, trace, and optimize your LangChain workflows.

​
Table of Contents

  1. Why Debugging Matters
  2. Enabling Debug & Verbose Logs
  3. Implementing Custom Callbacks
  4. Further Reading & Resources

​
Why Debugging Matters

Without clear logs, it’s nearly impossible to pinpoint where things went awry—in prompt construction, LLM invocation, or output parsing. Adding debug instrumentation helps you:
  • Trace prompt transformations
  • Inspect API payloads and responses
  • Identify latency and performance bottlenecks

​
Enabling Debug & Verbose Logs

LangChain provides built-in flags for detailed logging. You can turn them on in code or via environment variables.
OptionDescriptionExample Usage
verbose=TrueLogs API requests & responsespython<br>from langchain import OpenAI<br>llm = OpenAI(verbose=True)
LANGCHAIN_HANDLERSets the logging handler at runtimebash<br>export LANGCHAIN_HANDLER="langchain.debug"<br>python app.py
Enabling verbose or debug mode can produce large volumes of logs—use filters or log rotation to manage output size in production.

​
Implementing Custom Callbacks

Callbacks let you hook into LangChain’s lifecycle events to capture inputs, outputs, and metadata. 
from langchain.callbacks.base import BaseCallbackHandler
from langchain import OpenAI, LLMChain
from langchain.prompts import PromptTemplate

class DebugCallback(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kwargs):
        print("▶️ LLM Start:", prompts)

    def on_llm_end(self, response, **kwargs):
        print("✅ LLM End:", response)

# Define your prompt template
prompt = PromptTemplate(
    input_variables=["text"],
    template="Translate this to French: {text}"
)

# Initialize LLM with callback
llm = OpenAI(temperature=0.7)
chain = LLMChain(llm=llm, prompt=prompt, callbacks=[DebugCallback()])

# Run the chain
result = chain.run(text="Hello, world!")
print("Result:", result)
Heavy callback logic can slow down your chain. If you need extensive processing, consider batching or asynchronous handlers.

​
Further Reading & Resources

Watch Video