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 the agent’s answers are sent to whichever instance you configure. Warehouse data itself is not - see What is never sent. Self-host Langfuse if prompts and answers can’t leave your infrastructure. A Langfuse secret key also grants API access to read the project’s traces - treat it as sensitive.

​
What is never sent

Query data never reaches Langfuse. Everything belonging to the execute_sql and read_query_result tools - the SQL text, the returned rows, and any error message - is replaced with [redacted] before a trace leaves nao. The calls stay visible in the trace: you can still see that a query ran, how long it took, and whether it failed. Only the contents are gone. Redaction covers both places that data used to appear: the tool call itself, and the conversation history replayed on every following model call. Everything else is unchanged - questions, answers, other tools, timings, and token usage. It is always on, with no setting to turn it off.

​
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.