Observability (Langfuse)

DotAgents integrates with Langfuse to provide comprehensive monitoring, tracing, and debugging for all LLM calls and agent operations.

Note: Langfuse is an optional dependency. The app works perfectly without it. Only set it up if you want observability features.

---

What Gets Traced

Component	Captured Data
LLM Calls	Model name, input prompts, output responses, token usage
Agent Sessions	Complete workflow from start to finish
MCP Tool Calls	Tool name, input parameters, output results, execution status
Conversations	Session-level grouping of all interactions

Setup

1. Create a Langfuse Account

• Sign up at langfuse.com (free tier available)
• Or self-host using Langfuse's open-source deployment

2. Get API Keys

1. Go to your Langfuse project settings
2. Copy your Public Key (pk-lf-...)
3. Copy your Secret Key (sk-lf-...)

3. Configure in DotAgents

1. Open Settings > General (scroll to the bottom)
2. Toggle "Enable Langfuse Tracing" on
3. Enter your Public Key
4. Enter your Secret Key
5. (Optional) Set the Base URL for self-hosted instances

Viewing Traces

Sessions

Conversations are grouped by session ID:

• Replay entire conversation threads
• See all agent interactions within a conversation
• Track costs and token usage per conversation
• Debug multi-turn conversations end-to-end

Traces

Each agent session creates a trace containing:

• User input (voice transcription or text)
• All LLM generations with token counts
• All MCP tool calls with inputs/outputs
• Final output/response
• Agent tags (e.g., agent:General Assistant)

Generations

Individual LLM API calls showing:

• Model used (e.g., gpt-5.4-mini, gemini-3.1-pro-preview)
• Input messages/prompts
• Output response
• Token usage metrics (input/output/total)
• Latency

Spans

MCP tool executions showing:

• Tool name
• Input parameters
• Output results
• Execution time
• Success/error status

Langfuse Feature Mapping

Langfuse Feature	DotAgents Mapping
Sessions	Conversation ID — groups all interactions
Traces	Agent Session ID — individual agent run
Tags	Agent name (e.g., agent:General Assistant)
Generations	Individual LLM API calls with token usage
Spans	MCP tool executions with inputs/outputs

Self-Hosted Langfuse

For organizations requiring data privacy, set the base URL to your instance:

Base URL: https://your-langfuse-instance.com

Leave empty to use Langfuse Cloud (https://cloud.langfuse.com).

Privacy

• Traces include LLM inputs and outputs — be mindful of sensitive data
• API keys are stored locally in the app's config
• No data is sent to Langfuse when the integration is disabled

Debug Logging (Alternative)

For real-time debugging without Langfuse, use the built-in debug flags:

pnpm dev d               # ALL debug logging
pnpm dev debug-llm       # LLM calls only
pnpm dev debug-tools     # MCP tool execution only
pnpm dev debug-ui        # UI state changes only

See the Debug Reference for details.

---

Next Steps

• AI Providers — Configure LLM providers
• MCP Tools — Tool execution monitoring
• Debug Reference — Built-in debugging tools