diff --git a/src/assets/images/workers/observability/local-trace-failed-request.png b/src/assets/images/workers/observability/local-trace-failed-request.png new file mode 100644 index 00000000000..05676d73074 Binary files /dev/null and b/src/assets/images/workers/observability/local-trace-failed-request.png differ diff --git a/src/content/docs/workers/local-development/local-explorer.mdx b/src/content/docs/workers/local-development/local-explorer.mdx index 1db99753cd1..cef657ff037 100644 --- a/src/content/docs/workers/local-development/local-explorer.mdx +++ b/src/content/docs/workers/local-development/local-explorer.mdx @@ -9,11 +9,11 @@ products: - workers --- -import { Details, PackageManagers, InlineBadge } from "~/components"; +import { PackageManagers, Steps } from "~/components"; -Local Explorer is a browser-based interface for viewing and editing the data in your local [bindings](/workers/runtime-apis/bindings/) during development. It is available at `/cdn-cgi/explorer` on your local development server. +Local Explorer is a browser-based interface for viewing and editing the data in your local [bindings](/workers/runtime-apis/bindings/) and debugging Worker invocations during development. It is available at `/cdn-cgi/explorer` on your local development server. -Instead of running CLI commands or writing throwaway code to inspect local state, you can open Local Explorer in your browser and work with your data directly. This is useful when you want to seed test data, verify what your Worker wrote, debug a workflow run, or run ad-hoc SQL queries against a local [D1](/d1/) database. +Instead of running CLI commands or writing throwaway code to inspect local state, you can open Local Explorer in your browser to work with your data, view traces, and search logs. This is useful when you want to seed test data, verify what your Worker wrote, debug a failing request, or run SQL queries against a local [D1](/d1/) database. Local Explorer works with both [Wrangler](/workers/wrangler/) and the [Cloudflare Vite plugin](/workers/vite-plugin/). @@ -23,11 +23,15 @@ Local Explorer works with both [Wrangler](/workers/wrangler/) and the [Cloudflar ## Open Local Explorer + 1. Start a local development session: - + -2. Press `e` in your terminal to open Local Explorer in your browser. You can also navigate directly to `/cdn-cgi/explorer` on your Worker's route and port. +2. Open Local Explorer in your browser: + - **Wrangler**: press `e` in your terminal. + - **Vite plugin**: navigate directly to `/cdn-cgi/explorer` on your dev server's route and port. + Local Explorer is available by default and detects the bindings defined in your [Wrangler configuration](/workers/wrangler/configuration/) automatically. @@ -43,9 +47,25 @@ Local Explorer supports the following binding types: | [Durable Objects](/durable-objects/) (SQLite storage) | Browse SQLite tables and rows, run SQL queries | Insert, update, and delete rows through SQL | | [Workflows](/workflows/) | List instances, view status and step history | Trigger new runs, retry failed instances | -### D1 and Durable Objects SQL studio +### D1 and Durable Objects SQL Studio -For [D1](/d1/) databases and [Durable Objects](/durable-objects/) that use the [SQLite storage API](/durable-objects/api/sqlite-storage-api/), Local Explorer includes a SQL studio. This is the same experience available in the Cloudflare dashboard for deployed D1 databases. It provides both a visual table browser with inline editing and a SQL query editor where you can run arbitrary queries. +For [D1](/d1/) databases and [Durable Objects](/durable-objects/) that use the [SQLite storage API](/durable-objects/api/sqlite-storage-api/), Local Explorer includes a SQL Studio. This is the same experience available in the Cloudflare dashboard for deployed D1 databases. It provides both a visual table browser with inline editing and a SQL query editor where you can run arbitrary queries. + +## Observability + +Local Explorer automatically captures traces and logs from every Worker invocation during `wrangler dev` without modifying your code. You get the same instrumentation as production [Workers Logs](/workers/observability/logs/workers-logs/) and [Traces](/workers/observability/traces/), including invocation logs, binding operations, timing, and console output, directly in your browser during development. + +### Logs + +The **Logs** view captures all `console.*` output from your Worker. Filter by level (error, warn, info, log, debug) or search by text to find specific messages. + +### Traces + +Each Worker invocation appears as a trace. Select any trace to see every binding operation with timing, status, and error details. + +For example, if a request makes two D1 calls and the second one fails, the trace shows you exactly which call succeeded and which errored without adding `console.log()` or try/catch blocks. + +![Trace view for POST /api/todos showing two D1 database spans: the first INSERT succeeded, the second failed with error "no such table: audit_log"](~/assets/images/workers/observability/local-trace-failed-request.png) ## API @@ -57,9 +77,9 @@ To retrieve the OpenAPI spec: curl http://localhost:8787/cdn-cgi/explorer/api ``` -### Use with AI coding agents +### Use with AI agents -The OpenAPI spec at `/cdn-cgi/explorer/api` allows AI coding agents and other tools to discover and interact with your local bindings programmatically. An agent can fetch the spec, understand what resources are available, and make API calls to read or modify local data without requiring manual setup. +When Wrangler detects it is running inside an AI agent, it prints a hint with the Local Explorer API endpoint directly to the terminal. The agent can fetch the [OpenAPI specification](https://www.openapis.org/) from that endpoint to discover all available operations, then make API calls to read or modify local data, query traces and logs, and debug your Worker. This can be useful as an alternative to the CLI when you want an agent to: @@ -67,3 +87,5 @@ This can be useful as an alternative to the CLI when you want an agent to: - Inspect the state of a [Durable Object](/durable-objects/) during debugging - Trigger or retry a [Workflow](/workflows/) run with different input data - Upload test files to a local [R2](/r2/) bucket +- Find recent requests with errors and drill into failing spans + diff --git a/src/content/docs/workers/observability/index.mdx b/src/content/docs/workers/observability/index.mdx index 2a1cdae79d2..0fec40a67fb 100644 --- a/src/content/docs/workers/observability/index.mdx +++ b/src/content/docs/workers/observability/index.mdx @@ -2,7 +2,7 @@ pcx_content_type: navigation title: Observability sidebar: - order: 16 + order: 15 head: [] description: Understand how your Worker projects are performing via logs, traces, metrics, and other data sources. products: @@ -74,6 +74,11 @@ The [Query Builder](/workers/observability/query-builder/) helps you write struc href="/workers/observability/dev-tools/" description="Use Chrome DevTools for breakpoints, CPU profiling, and memory debugging during local development." /> + ## Additional resources