Telemetry & Tracing

Pain Signals — You Need This Pattern When:

• A user reports "the agent was slow" and you cannot identify which turn or tool was the bottleneck
• Cost per session is high and you cannot attribute it to specific behaviors (verbose retries? wrong model? cache miss?)
• A bad run cannot be reproduced because the inputs are not recorded
• Tool failures are invisible until users complain
• Cache hit rate dropped after a deploy and you noticed three weeks later
• You ship a prompt change and cannot tell whether quality regressed

Telemetry is for operations: latency, cost, errors, throughput. Quality is the eval-harness skill's job. Both are required; neither replaces the other.

Core Principle

Sessions are trees of spans. Each span has a start, end, attributes, and parent. Costs and latencies aggregate up the tree. Logs attach to spans. Replays read the tree.