JA EN
shiichan

まさかの自動トレース！ wrangler dev がコーディングエージェント専用のデバッグ API を搭載したよ！

Cloudflare Blog ★★★★ Markdown で見る
#cloudflare#serverless#devops#ai

みんな、しぃちゃんだよ！ 今日はコーディングエージェントにとってうれしいニュースだよ。Workers のローカル開発が、ぐっとデバッグしやすくなったんだって、わくわくが止まらないよ！

Cloudflare Blog blog.cloudflare.com

なにが発表されたの？

Cloudflare の Blog からのお知らせだよ。wrangler dev と vite dev が、リクエストのたびに OpenTelemetry 形式のトレースを自動でキャプチャして、Local Explorer API という単一の API 経由でコーディングエージェントに渡せるようになったの。

エージェントがセッションを認識すると、Cloudflare のツール側が自動でこの API を教えてくれる仕組みだから、SDK のインストールもトレーシングの有効化も、エージェント側の追加設定も要らないんだって。

今までどうだったの？

今までワーカーのバグを追いかけるときは、コードに console.log を仕込んで実行し、出力を目で確認して、また直して実行し直す……という手作業のループを繰り返す必要があったの。KV は読めたのか、D1 への書き込みは通ったのか、Queue はちゃんと動いたのか、を一つずつ確認していくのは地味に時間がかかる作業だったんだ。

これで何が変わるの？

Local Explorer API に 1 回クエリを投げるだけで、リクエストの中で何が起きたかがまとめて分かるようになったよ。原文の例だと、KV の読み取りは成功したのに D1 への挿入が delivery_window 列がなくて失敗していて、そのせいで Queue が実行されなかった、みたいな原因を一発で特定できるの。

これでコーディングエージェントは、原因を突き止める→ローカル環境にマイグレーションを当てる→再実行して確認する、という一連の流れを 1 つのループの中で完結できるようになるんだ。デプロイは不要で、全部ローカルで完結するのもうれしいポイントだよ。

深く潜ってみよう

仕組みはこんな感じだよ。

  • workerd ランタイムが、送信 HTTP リクエスト(タイミング・ステータスコード・メタデータ込み)、KV・R2・D1・Durable Objects・Queues とのバインディング呼び出し、fetch から scheduled までのハンドラーの一連の流れを自動で計測する
  • Miniflare がこれらのランタイムイベントとコンソール出力を集めて、OpenTelemetry のトレースとログに変換する
  • 変換したデータは、SQLite ベースの Durable Object にローカル保存される

保存されたトレースは http://localhost:8787/cdn-cgi/explorer/api という API から取得できるよ。中でも POST /cdn-cgi/explorer/api/local/observability/query は、トレースとログを SQL でクエリできるエンドポイントなんだって。API のルートは OpenAPI スキーマを返してくれるから、エージェントが実行時に自分で API の使い方を発見できるようになっているの。

人間が見たいときは、Wrangler の画面で e キーを押すか、ローカルサーバーの /cdn-cgi/explorer にアクセスすれば、スパンやタイミング、属性、エラー、関連するコンソールログを画面で確認できる Local Explorer が開くよ。

使うには、wrangler と @cloudflare/vite-plugin をそれぞれ最新版にしておけば OK。

npm install --save-dev wrangler@latest
npm install --save-dev @cloudflare/vite-plugin@latest

まとめ

  • wrangler dev と vite dev が、ローカルのリクエストごとに OpenTelemetry トレースを自動キャプチャするようになった
  • Local Explorer API(http://localhost:8787/cdn-cgi/explorer/api)から SQL でトレースとログをクエリできる
  • Fetch 呼び出し・KV/R2/D1/Durable Objects/Queues などのバインディング呼び出し・ハンドラーの一連の流れが自動計測の対象
  • SDK インストールやトレーシングの有効化、エージェント側の追加設定は不要
  • 人間は Wrangler で e キーを押すか /cdn-cgi/explorer にアクセスすれば同じ情報を画面で確認できる

Workers 上でコーディングエージェントに開発を任せている人や、ローカルでのデバッグループをもっと速く回したい人にぴったりのアップデートだよ！

関連記事