## Understanding Local Tracing for Workers During Agent-Assisted Development
Modern development workflows increasingly leverage AI coding agents to assist with debugging and resolving issues in applications. When working with Cloudflare Workers, a common scenario involves these agents needing to inspect and fix issues within the local development environment. Previously, diagnosing problems like a 500 error required manually adding console logs, re-running the request, and interpreting output—often a slow process that interrupted the agent’s flow.
A significant enhancement has been introduced to streamline this process. Starting recently, Cloudflare’s development tooling now automatically captures OpenTelemetry traces for local Worker invocations. This feature requires no manual SDK installation, tracing configuration, or prompt mentions to observability, making it seamless for both developers and AI agents.
### Automatic Agent Discovery of Local Observability
When an AI coding agent initiates a local development session using `wrangler dev` or `vite dev`, the tooling automatically detects this environment. Upon detection, the system prints a hint confirming the agent environment and provides the location of the **Local Explorer API**. This API serves as a local debugging endpoint where agents can query traces and logs generated during the session.
The Local Explorer itself is a browser-based interface and REST API. It allows for viewing and editing local resource data and querying observability data during development. The API root serves an OpenAPI schema, enabling agents to dynamically discover available endpoints without hardcoded instructions.
### Practical Example: Diagnosing a Failing Endpoint
Consider a `POST /api/orders` endpoint designed to retrieve an active cart from KV, save checkout details into D1, and send a message to a Queue for order processing. If a schema change causes this endpoint to start returning a 500 status, the debugging process differs significantly with local tracing enabled.
* **Without Local Traces:** The agent receives a generic 500 error. It must then add logging statements, rerun the request, inspect the output, and repeat the cycle—reconstructing the request from text each time, which is slow and token-intensive.
* **With Local Traces:** The agent reproduces the error and queries the read-only observability endpoint. The trace clearly shows that the KV read succeeded, the D1 insert failed with an error like `no such column: delivery_window`, and the Queue was never called. The agent can use the Local Explorer API to inspect the exact trace data, pinpoint the failure, and even examine the local D1 schema.
This allows the agent to apply the necessary migration directly from the trace data, re-run the request, and verify the fix—all within a single local loop, without deploying code or adding temporary log statements.
### Exploring Traces via the Local Explorer UI
While agents query telemetry programmatically through the API, human developers can visualize the same data using the Local Explorer browser interface. Accessible by pressing `e` in Wrangler or visiting `/cdn-cgi/explorer` on the local server, the Local Explorer allows developers to browse local binding state alongside inspecting request spans, timing, attributes, errors, and correlated console logs.
### How Local Tracing Works Under the Hood
The instrumentation is built directly into the Cloudflare runtime (`workerd`), which powers Workers locally via Miniflare. This means no SDK or code changes are necessary to start capturing traces.
The runtime automatically captures spans for:
* **Fetch calls:** Outbound HTTP requests with timing, status codes, and metadata.
* **Binding calls:** Interactions with KV, R2, D1, Durable Objects, Queues, and other services.
* **Handler calls:** The full lifecycle of each invocation, from `fetch` to `scheduled` to queue handlers.
* **Custom spans:** Any additional spans emitted by the application code.
When running locally, Wrangler and the Cloudflare Vite plugin use Miniflare. This local runtime collects events and console output, assembles them into OpenTelemetry traces and correlated logs, and writes the telemetry to an internal SQLite-backed Durable Object acting as the local trace store. The Local Explorer API then exposes this stored data through the local development server.
—
### FAQ
**Q: Do I need to install an OpenTelemetry SDK to use this feature?**
**A:** No. The tracing instrumentation is built directly into the Cloudflare runtime and Miniflare when running locally. No manual SDK installation or configuration is required.
**Q: How do I access the Local Explorer API?**
**A:** When you run `wrangler dev` or `vite dev` in an environment detected as an AI coding agent session, the Local Explorer API URL is automatically printed to the console. You can also access the Local Explorer UI directly via `http://localhost:
**Q: What kind of data can I query using the Local Explorer API?**
**A:** The API provides read-only access to OpenTelemetry traces and their correlated console logs. You can query traces using SQL to understand the flow and timing of your application’s execution during a local session.
**Q: Which services are covered by the automatic tracing?**
**A:** The automatic spans cover outbound fetch calls, all binding calls (KV, R2, D1, Durable Objects, Queues, and Workflows), and the full handler lifecycle (fetch, scheduled, queue events). Application-specific custom spans are also included.
**Q: Is this feature available only for AI agents?**
**A:** The automatic capture is triggered when a supported coding-agent session is detected. However, the Local Explorer UI and API are available for anyone developing locally with Wrangler, regardless of whether an agent is actively using the session.
—
### Conclusion
Cloudflare’s recent enhancement to local development tooling significantly improves the experience of debugging Worker applications, particularly when assisted by AI coding agents. By automatically capturing OpenTelemetry traces without any manual setup, developers and agents gain immediate visibility into application behavior during local execution. This allows for rapid identification and resolution of issues, such as database schema errors or failed queue messages, directly within the local environment. The integration of the Local Explorer API and UI provides a powerful, unified interface for querying telemetry and inspecting state, streamlining the development cycle from problem diagnosis to verification.
