Cloudflare cho phép debug Workers với tracing cục bộ

Cloudflare vừa bổ sung tính năng OpenTelemetry tracing tự động cho Workers khi phát triển cục bộ bằng wrangler dev và vite dev. Tính năng này giúp các coding agent debug Workers trực tiếp thông qua Local Explorer API mà không cần cài đặt SDK hay cấu hình. Tracing ghi lại các lệnh gọi fetch, tương tác với binding và vòng đời handler, hỗ trợ xác định và giải quyết vấn đề trước khi triển khai.

Agent có thể đơn giản yêu cầu: POST /api/orders is returning 500. Find the cause, fix it, and verify the fix locally. Đây là kết quả của quá trình đầu tư vào phát triển cục bộ, từ Miniflare đến chế độ local mặc định trong Wrangler 3. Local traces cung cấp phản hồi có cấu trúc cho agent từ môi trường phát triển trước khi code được triển khai.

Agent tự động khám phá Local Explorer API

Agent khởi động wrangler dev hoặc vite dev để chạy và kiểm thử Worker. Khi server phát hiện session agent được hỗ trợ, nó tự động hiển thị thông báo:

`This dev session is running in an AI agent.

The Local Explorer API is available at http://localhost:8787/cdn-cgi/explorer/api`

...

Debug with traces: POST /cdn-cgi/explorer/api/local/observability/query -- query traces and logs with SQL

Local Explorer là giao diện trình duyệt và REST API để xem và chỉnh sửa dữ liệu resource cục bộ, truy vấn dữ liệu observability trong quá trình phát triển. API root cung cấp OpenAPI schema, giúp agent khám phá các endpoint có sẵn mà không cần chỉ dẫn cứng.

Tìm lỗi và xác minh sửa lỗi

Ví dụ, endpoint POST /api/orders lấy giỏ hàng từ KV, lưu chi tiết thanh toán vào D1 và gửi tin nhắn đến Queue để xử lý đơn hàng. Sau thay đổi schema, endpoint bắt đầu trả về status 500.

Không có local traces

Status 500 không chỉ rõ thao tác nào thất bại. Agent thêm log xung quanh KV, D1 và Queue, chạy lại request, kiểm tra output và lặp lại. Mỗi chu kỳ tốn thời gian và tiêu tốn token khi agent tái tạo request từ text.

Có local traces

Agent tái hiện lỗi và truy vấn observability endpoint. Trace cho thấy KV read thành công, D1 insert thất bại do không có cột delivery_window, và Queue không được gọi. Agent sử dụng Local Explorer API để kiểm tra schema D1. Agent thấy migration thêm delivery_window tồn tại trong repository nhưng chưa được áp dụng cục bộ, áp dụng nó, gửi lại request và truy vấn trace mới. Vấn đề được giải quyết.

Trong một vòng lặp cục bộ, agent xác định thao tác thất bại, sửa môi trường cục bộ và xác minh kết quả mà không cần triển khai hoặc thêm log tạm thời.

Khám phá traces và logs trong Local Explorer

Agent truy vấn telemetry cục bộ thông qua API, nhưng bạn có thể trực quan hóa dữ liệu tương tự trong Local Explorer, giao diện trình duyệt tích hợp trong local development server. Bên cạnh việc duyệt state binding cục bộ, bạn có thể chọn request để kiểm tra spans, thời gian, thuộc tính, lỗi và logs liên quan.

Local Explorer chạy trên cùng localhost origin với Worker, không phải trên Cloudflare dashboard. Nhấn e trong Wrangler hoặc truy cập /cdn-cgi/explorer trên local server để mở nó.

Cơ chế hoạt động

Khi ra mắt Workers Tracing, Cloudflare đã xây dựng instrumentation trực tiếp vào workerd, runtime open-source hỗ trợ Workers. Không cần SDK hay thay đổi code, runtime ghi lại spans cho: fetch calls (tất cả HTTP requests outbound, bao gồm thời gian, status code và metadata request), binding calls (mọi tương tác với KV, R2, D1, Durable Objects, Queues và bindings khác), và handler calls (toàn bộ vòng đời của mỗi invocation, từ fetch đến scheduled và queue handlers). Bất kỳ custom spans nào được phát ra bởi ứng dụng của bạn cũng sẽ xuất hiện cùng với các spans tự động này.

Wrangler và Cloudflare Vite plugin sử dụng Miniflare để chạy Worker cục bộ trong cùng runtime, giúp instrumentation này khả dụng trong quá trình phát triển cục bộ.

Miniflare thu thập runtime events và console output, tạo OpenTelemetry traces và logs liên quan, sau đó ghi telemetry vào Durable Object dựa trên SQLite, đóng vai trò là local trace store. Local Explorer API cung cấp dữ liệu này thông qua local development server, nơi agent có thể dễ dàng truy vấn traces và logs, kiểm tra state cục bộ.

Bắt đầu

Cập nhật Wrangler hoặc Cloudflare Vite plugin:

# Wrangler
npm install --save-dev wrangler@latest

# Cloudflare Vite plugin
npm install --save-dev @cloudflare/vite-plugin@latest

Sau đó, yêu cầu agent debug cục bộ như bình thường. Agent có thể viết và chạy Worker cục bộ — giờ nó có thể thấy điều gì xảy ra, sửa lỗi và xác minh kết quả trước khi triển khai. Xem docs để biết thêm chi tiết!

Câu hỏi thường gặp

Local Explorer API có sẵn ở đâu?

Local Explorer API có sẵn tại http://localhost:8787/cdn-cgi/explorer/api khi chạy wrangler dev hoặc vite dev.

Tracing cục bộ ghi lại những thông tin gì?

Tracing cục bộ ghi lại các lệnh gọi fetch, tương tác với binding (KV, R2, D1, Durable Objects, Queues) và vòng đời handler.

Miniflare đóng vai trò gì trong quá trình này?

Miniflare chạy Worker cục bộ trong cùng runtime với workerd, giúp instrumentation khả dụng trong quá trình phát triển cục bộ. Nó thu thập events, tạo traces và logs, rồi lưu trữ trong local trace store.