LangChain

Trace an existing LangChain application with the Noveum callback handler.

NoveumTraceCallbackHandler records LangChain runnable, model, retriever, and tool callbacks as one connected trace. Add it at the top-level invocation so callbacks propagate through the complete workflow.

Install the tracing package

This guide assumes the application already has LangChain and its provider packages installed.

pip install noveum-trace

Initialize Noveum Trace

Initialize once before creating the callback handler:

import os

import noveum_trace

noveum_trace.init(
    api_key=os.environ["NOVEUM_API_KEY"],
    project=os.environ["NOVEUM_PROJECT"],
    environment=os.getenv("NOVEUM_ENVIRONMENT", "production"),
    service_version=os.environ["NOVEUM_SERVICE_VERSION"],
)

Use NOVEUM_SERVICE_VERSION for the prompt, model, tool, retrieval, and routing behavior being traced. Change it when that behavior changes.

Add the callback

Pass the handler in the runtime config of the highest-level runnable:

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from noveum_trace.integrations.langchain import NoveumTraceCallbackHandler

prompt = ChatPromptTemplate.from_template("Summarize this text: {text}")
chain = prompt | ChatOpenAI(model="gpt-4o-mini") | StrOutputParser()
handler = NoveumTraceCallbackHandler()

result = chain.invoke(
    {"text": document},
    config={"callbacks": [handler]},
)

Invocation-level configuration captures the parent chain as well as nested model, retriever, and tool callbacks. A handler attached only to a model cannot observe the surrounding chain or agent lifecycle.

For a short-lived process, flush after all invocations finish:

noveum_trace.flush()

Long-running services should flush during graceful shutdown after they stop accepting work.

What is captured

The handler uses the callback data LangChain supplies:

Callback	Trace evidence
Runnable or chain	Inputs, outputs, duration, parent run, tags, metadata, and errors
LLM or chat model	Ordered prompts or messages, generations, model metadata, and reported usage
Retriever	Retrieval query and returned documents
Tool	Tool input, output, duration, and errors

Capture depends on what each component emits. Open a representative trace and verify that the evidence required by your ETL mapper is present rather than assuming every provider reports the same fields.

Protect sensitive payloads

NoveumTraceCallbackHandler does not provide per-field capture toggles. Redact sensitive values before invocation, or do not attach the handler to workflows whose payloads must not leave the application.

Never include credentials, authorization headers, or private keys in prompts, tool arguments, metadata, or outputs.

Verify the integration

Run a successful request and a controlled failure, then confirm:

the top-level runnable owns the complete trace
model, retriever, and tool operations appear as children when used
model inputs, outputs, and usage are present
retrieval results and tool results are attached to their operations
errors have the expected status and message
the trace has the intended environment and service version

Use the trace design guide to review span boundaries and the evaluation capture contract to review required payloads. For stateful graphs, continue with the LangGraph integration.

Source

NoveumTraceCallbackHandler