Skip to main content
nao can export a trace of every LLM call to Langfuse: prompt, response, latency, tokens, cost, model, and tool calls. It’s off by default; running without it needs no action.

​
Configuration

All three are required. If any is missing, tracing stays off and nao starts normally. LANGFUSE_BASE_URL has no default by design, so traces are never sent to a destination you didn’t name. On Langfuse Cloud, use the host shown in your project settings - keys are region-bound, so a URL from another region fails authentication. Self-hosted Langfuse works identically - use your instance URL, including an internal one like http://langfuse-web:3000. It must be version 3.63.0 or newer.
Traces include the full text of prompts and responses, so user questions and query results are sent to whichever instance you configure. Self-host Langfuse if that data can’t leave your infrastructure. A Langfuse secret key also grants API access to read the project’s traces - treat it as sensitive.

​
Set the variables

nao chat - add them to a .env file in your project folder. nao loads it on startup and passes it to the agent:
Docker - add -e flags:
Docker Compose - same three lines in the .env file next to docker-compose.yml, which already forwards them. Then run docker compose up -d.

​
Verify

On startup nao logs ✓ Langfuse tracing enabled → <url>. Send a message in the chat and a nao-agent trace appears in your Langfuse project.
Traces are batched and ingested asynchronously, so one can take a little while to show up. That delay is normal.

​
What you see in Langfuse

Traces are named after the operation that produced them: Each trace carries the chat as the Langfuse session (so Sessions groups a whole conversation), the nao user as the user, and the model provider as a tag. Model name and any custom sampling settings (temperature, top-p, top-k) are attached as metadata.