Observability

Talon integrates with Langfuse for production observability. Every agent run, sub-agent invocation, MCP tool call, and context rotation is traced and exportable.

Setup

Create a Langfuse account (cloud or self-hosted)
Create a project and copy the public/secret key pair
Add the keys to your environment:

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...

Enable in talond.yaml:

langfuse:
  enabled: true
  publicKey: ${LANGFUSE_PUBLIC_KEY}
  secretKey: ${LANGFUSE_SECRET_KEY}

Configuration

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable tracing
`publicKey`	string	—	Langfuse public key (required when enabled)
`secretKey`	string	—	Langfuse secret key (required when enabled)
`baseUrl`	string	`https://cloud.langfuse.com`	Langfuse instance URL (for self-hosted)
`environment`	string	`production`	Environment tag on all traces
`release`	string	—	Version tag
`owner`	string	—	Owner tag
`exportMode`	`batched \| immediate`	`batched`	`batched` buffers events for efficiency; `immediate` flushes on every event
`flushAt`	integer	`20`	Batch size before auto-flush
`flushIntervalSeconds`	integer	`5`	Max seconds between flushes

What gets traced

Each trace corresponds to one agent run (one queue item processed). Within a trace, Langfuse shows:

Span	Description
Agent run	Top-level trace — persona, thread, provider, model, duration
Generation	Each LLM call with input/output tokens, cost, model ID
Tool call	Each tool invocation — host tools, MCP tools, sub-agents
Context assembly	System prompt construction including memory retrieval
Sub-agent	Nested traces for sub-agent invocations (session-summarizer, memory-groomer, etc.)
Context rotation	Session rotation events with before/after token counts

Token usage (input, output, cache read, cache write) and cost are attached to each generation span.

Interpreting the data

Cost per persona

Filter traces by persona name to see which agents cost the most. Compare input vs. cache-read tokens to gauge prompt cache efficiency.

Context rotation frequency

Look for context rotation spans. If they fire too often, increase thresholdRatio. If they never fire, your conversations might be short enough that rotation isn’t needed.

Sub-agent overhead

Sub-agent invocations appear as nested traces. If session-summarizer or memory-groomer runs are expensive, consider adjusting their scheduling or switching them to a cheaper model.

Latency breakdown

Each span shows wall-clock duration. Use this to identify whether latency comes from the LLM call, tool execution, or context assembly.

Self-hosted Langfuse

For air-gapped or on-premises deployments, point baseUrl to your Langfuse instance:

langfuse:
  enabled: true
  publicKey: ${LANGFUSE_PUBLIC_KEY}
  secretKey: ${LANGFUSE_SECRET_KEY}
  baseUrl: https://langfuse.internal.example.com