Cloudflare Agent Tracing: A Debugging Tool, Not an Audit Trail

Cloudflare shipped agent tracing on August 15, 2026, the first feature in its new Agents dashboard. The release adds agent-level spans to Workers tracing that already covers fetch calls, KV reads, and D1 queries. It is free during beta; from October 1, 2026, it falls under Workers Observability pricing.

The problem is real. An agent can return HTTP 200 and still fail: pick the wrong tool, pass stale context to a subagent, or burn tokens in a retry loop. Application telemetry sees the API request and database query but not the agent behavior that triggered them. Agent tracing adds spans for agent invocations, model calls, tool execution, and approvals, with model identity and token usage as metadata. Each turn produces one trace: `invoke_agent {agent class}` at the root, with `chat {model}` and `execute_tool {tool}` nested below, and `tool_approval {tool}` under that. Subagent work nests under the parent operation that invoked it.

Three fields wire spans to the dashboard: agent name (logical implementation), agent ID (instance), and conversation ID. Cloudflare warns against deriving agent name from request or user identifiers—that fragments one agent into many in the view. Session replay reconstructs conversations across turns from recorded messages, reasoning, tool calls with arguments and results, and subagent activity. Cloudflare does not re-execute the agent; replay uses stored data only.

Payload defaults demand audit. Think does not store message or tool payloads unless `storeMessages` and `storeTools` are set on the agent class; `wrapAISDK()` behaves identically. Flue stores messages, system instructions, tool definitions, arguments, and results by default, requiring `content: false` to opt out. The same feature ships with opposite privacy defaults depending on which harness teams chose. Message payloads routinely carry personal data or secrets; the discrepancy is not academic.

Documented limitations constrain replay trust. Cloudflare states traces are not complete or lossless: payload data hits span size limits, so long messages, reasoning, tool arguments, and results may truncate. Session replay does not display images. Retention is 3 days on Workers Free, 7 days on Workers Paid—too short for recurring pattern analysis, suitable for recent incidents only.

Pricing counts per span, not per dashboard display. Every span counts, including SDK internals and Worker-level operations the view does not surface. Workers Free covers 200,000 events per day; Workers Paid includes 20 million per month with additional millions at $0.60 each. A verbose harness or deeply nested subagent graph will run up a bill that dashboard alone will not predict. One approval span records a lifecycle event; it does not measure human response latency across invocations—HITL latency is not captured.

Instrumentation paths differ by stack. Think and Flue v2 or later instrument turns automatically. Direct AI SDK calls need a `wrapAISDK()` wrapper (v6 and v7 supported), with identity fields supplied on each call. Custom harnesses use the Workers custom spans API following OpenTelemetry GenAI reference implementations. Workers does not yet support the OpenTelemetry API directly, though Cloudflare is working on it. Span attributes follow OTel Generative AI semantic conventions and export to any OTLP endpoint.

Agent tracing gives infrastructure teams a real debugging surface. Inconsistent payload defaults and truncation limits make it a debugging aid, not an audit trail. Plan accordingly before October billing starts.