LangChain

Attach the Neatlogs callback handler to your LangChain/LangGraph calls and LLM calls, chains, tools, and retrievers all become spans — including LangGraph node boundaries and tool loops. A run self-roots, so a single call renders a complete trace with no extra wrapper.

Prerequisites

pip install -U neatlogs langchain-openai

Usage

import os
import neatlogs

neatlogs.init(
    api_key=os.environ["NEATLOGS_API_KEY"],
    workflow_name="langchain-demo",
)

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o")

# Attach the Neatlogs callback handler to your LangChain calls.
handler = neatlogs.langchain_handler()
print(llm.invoke("In one sentence, what is LangChain?", config={"callbacks": [handler]}).content)

neatlogs.flush()
neatlogs.shutdown()

The instrumented run opens a WORKFLOW root automatically — even a bare llm.invoke() renders on its own. To group several calls (or your own @span functions) under one trace, wrap the entry point with a root; see Grouping calls into one trace.

LangGraph

For LangGraph, use the same callback handler — neatlogs.langchain_handler() in Python, langchainHandler() in TypeScript. LangGraph runs on LangChain's callback system, so no LangGraph-specific setup is needed.

LangGraph note (both languages): attach the handler at the graph invocation — app.invoke(inputs, config={"callbacks": [handler]}) in Python, app.invoke(inputs, { callbacks: [handler] }) in TypeScript (and likewise stream / ainvoke / astream / astream_events / batch) — not on the per-node llm.invoke(). LangGraph fires each node's on_chain_start only on the graph-level callback manager, so a handler passed to a single node's model call never sees the node boundaries: you get no node spans and the LLM span orphans to the workflow root. Attach once at the graph invocation and every node gets its own span with the LLM nested under it. (This is the opposite of plain LangChain / LCEL, where you attach per model/chain call as shown above.)

Use one handler instance for the whole run — build it once (handler = neatlogs.langchain_handler()) and reuse it. Creating a fresh handler per call splits the trace: those LLM spans never see the node and orphan to the root.

async def my_node(state, config=None):          # LangGraph injects config
    resp = await llm.ainvoke(msgs, config=config)  # pass it down
    return {"messages": [resp]}

# same single handler at the graph:
await app.ainvoke(inputs, config={"callbacks": [handler]})

Sessions & end-user

Say you're running a chatbot or any back-and-forth flow and want every turn to land under one session. The instrumented run opens a WORKFLOW root automatically, so wrap each turn in identify() and that root — plus every LangChain span beneath it — picks up the session and end-user:

# Same session_id every turn → one session; end_user_id attributes it to your user.
with neatlogs.identify(session_id=f"conv_{conversation_id}", end_user_id=user_id):
    llm.invoke(message, config={"callbacks": [handler]})

The trick is simply reusing the same session_id across turns so they stitch together into one conversation.

Not every run is a conversation. A standalone workflow — a one-off job, not a back-and-forth — is a single trace with no turns to group. You still attribute it to the customer it ran for, sourcing the id and any metadata from your own user or request object:

def run_chain(document, user):
    # Standalone workflow — attribute to the end-user; do NOT pass session_id.
    with neatlogs.identify(
        end_user_id=str(user.id),
        end_user_metadata={"plan": user.plan},
    ):
        return chain.invoke({"document": document}, config={"callbacks": [handler]})

For the full picture, head to Sessions and End-User Identity.