로컬 개발에서 에이전트가 자동으로 추적을 활용하도록 지원

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Cloudflare의 로컬 개발 서버(wrangler dev와 Vite 플러그인)가 OpenTelemetry 형식으로 자동 트레이스를 캡처하고 Local Explorer API를 통해 에이전트와 개발자가 동일한 관찰성 데이터를 조회할 수 있게 됐습니다. Miniflare가 런타임 이벤트와 콘솔 로그를 모아 내부 SQLite 기반 Durable Object에 기록하며 API 루트의 OpenAPI 스키마를 통해 에이전트가 엔드포인트를 동적으로 발견합니다. 결과적으로 코딩 에이전트는 로그를 반복해 추가할 필요 없이 한 루프 내에서 실패 지점을 식별하고 로컬 환경을 수정해 재검증할 수 있습니다.

섹션별 상세

로컬 개발 서버(wrangler dev와 vite dev)가 OpenTelemetry 형식의 추적을 자동으로 캡처해 Local Explorer API를 통해 제공하는 기능이 추가되었습니다. 개발자는 별도의 SDK 설치나 설정 변경 없이 로컬에서 발생한 Worker 호출의 스팬과 상관된 콘솔 로그를 조회할 수 있고, 이 데이터는 에이전트가 자동으로 발견해 쿼리할 수 있습니다. 이러한 자동화는 에이전트가 반복적인 로그 삽입과 재실행으로 시간을 소비하는 대신 구조화된 텔레메트리를 바로 읽어 실패 지점을 찾아내게 합니다.

근거

wrangler dev와 vite dev가 로컬 Worker 호출에 대해 OpenTelemetry 트레이스를 자동으로 캡처한다 — 문단 첫머리: "Starting today, wrangler dev and vite dev automatically capture OpenTelemetry traces for local Worker invocations."

코딩 에이전트는 wrangler dev 또는 vite dev를 실행하면 개발 서버가 AI 에이전트 세션을 감지하고 Local Explorer API 엔드포인트를 에이전트에 안내합니다. 에이전트는 API 루트에서 OpenAPI 스키마를 읽어 사용할 수 있는 엔드포인트를 런타임에 동적으로 발견하며, 추적 조회용 read-only 관찰성 엔드포인트와 로컬 바인딩 및 상태 검사용 연산을 혼합해 사용합니다. 이 흐름은 에이전트가 하드코딩된 명령 없이도 필요한 텔레메트리와 상태를 탐색하도록 구성된 것이 핵심입니다.

근거

에이전트는 Local Explorer API의 OpenAPI 스키마를 읽어 런타임에 엔드포인트를 발견할 수 있다 — 본문: "The API root serves an OpenAPI schema, so agents can discover available endpoints at runtime without hardcoded instructions."

실제 디버깅 예시로 POST /api/orders가 500을 반환할 때의 비교를 들고 있습니다. 추적이 없으면 에이전트가 KV·D1·Queue 주변에 임시 로그를 추가하고 여러 차례 재시도하면서 요청을 재구성해야 했지만, 로컬 트레이스가 있으면 에이전트가 실패한 스팬을 직접 조회해 D1 삽입에서 'no such column: delivery_window' 오류가 발생한 것을 바로 확인합니다. 그 증거를 바탕으로 에이전트는 리포지토리의 마이그레이션 적용 여부를 검사하고 로컬에 누락된 마이그레이션을 적용한 뒤 재검증해 문제를 한 루프 내에서 해결합니다.

Local Explorer는 브라우저 기반 UI와 REST API를 동시에 제공해 사람 개발자와 에이전트가 동일한 데이터를 확인할 수 있게 합니다. UI에서는 요청별로 스팬 타이밍, 속성, 오류, 상관된 콘솔 로그를 시각적으로 확인할 수 있고 API는 같은 정보를 기계가 쿼리하도록 노출합니다. Local Explorer가 로컬 서버의 동일 origin에서 동작하기 때문에 클라우드 대시보드와 분리된 로컬 전용 관찰성 창을 제공합니다.

계측 방식은 workerd 런타임 수준에서 구현되어 있어 Fetch 호출, 바인딩 접근(KV, R2, D1, Durable Objects, Queues 등), 핸들러 호출 수명주기 같은 이벤트를 자동으로 스팬으로 기록합니다. Miniflare가 이 런타임 계측을 수집해 OpenTelemetry 트레이스로 조립하고, 내부 SQLite-backed Durable Object에 저장해 Local Explorer API가 읽을 수 있게 합니다. 이 구조는 애플리케이션 코드 변경 없이도 자동 스팬과 사용자 정의 스팬을 함께 수집해 로컬에서 동일한 관찰성 경험을 제공하도록 설계되어 있습니다.

근거

Miniflare는 트레이스와 콘솔 출력을 수집해 SQLite-backed Durable Object에 기록하고 Local Explorer API가 이를 노출한다 — 본문: "Miniflare collects runtime events and console output, assembles them into OpenTelemetry traces and correlated logs, then writes the telemetry to an internal SQLite-backed Durable Object... The Local Explorer API exposes that data"

시작 방법은 Wrangler나 Cloudflare Vite plugin을 최신으로 업데이트한 뒤 기존대로 에이전트에게 로컬 디버그를 지시하면 됩니다. 문서에 안내된 명령이나 URL을 통해 Local Explorer를 열고(traces 페이지 등) 추적과 로그를 확인하면 에이전트가 자동으로 해당 API를 발견해 쿼리를 수행합니다. 따라서 개발자는 배포 없이 로컬 루프에서 문제를 확인하고 수정·검증하는 워크플로우를 빠르게 통합할 수 있습니다.

이미지 분석

Screenshot
이 스크린샷은 선택한 요청의 스팬 타이밍 바와 각 스팬의 지속시간, 오류 표시, 그리고 하단에 노출된 속성 테이블을 함께 보여줍니다. 화면 상단의 타임스탬프·요청 경로·Duration 컬럼과 하단의 faas.request.method, url.full, http.response.status_code 같은 속성들이 실제 추적 쿼리 결과와 대응함을 확인할 수 있습니다. 에이전트가 이 API를 쿼리해 동일한 필드로 실패 원인을 판별하는 흐름을 시각적으로 뒷받침합니다.
Local Explorer의 트레이스 상세 화면을 보여주는 스크린샷

Screenshot
요청 목록 화면은 여러 요청의 타임스탬프, Operation(요청 경로), Duration, Spans, Errors 정보를 일람할 수 있게 구성되어 있습니다. 이 뷰는 에이전트가 실패가 빈번한 엔드포인트를 우선적으로 찾거나 특정 시점의 트레이스를 선택해 상세 스팬으로 내려가는 작업을 반복하는 흐름과 일치합니다. 로컬에서 발생한 여러 호출을 비교해 패턴을 확인하는 데 유용한 인터페이스임을 보여줍니다.
Local Explorer의 요청 목록(트레이스 로그) 화면을 캡처한 스크린샷

용어 해설

OpenTelemetry: — 분산 트레이싱 표준인 OpenTelemetry는 애플리케이션의 요청 흐름을 스팬으로 기록하고 메타데이터를 붙여 추적 데이터를 생성합니다. 이 기사에서는 런타임에서 자동으로 스팬을 캡처해 로컬에서 조회 가능한 형태로 노출하는 방식으로 활용됩니다. 에이전트는 이 추적 데이터를 쿼리해 실패 지점을 빠르게 탐지할 수 있습니다.
Miniflare: — Miniflare는 Cloudflare Workers를 로컬에서 실행하는 런타임으로, workerd와 동일한 계측을 로컬 개발 환경으로 이식합니다. Miniflare는 런타임 이벤트와 콘솔 출력을 수집해 OpenTelemetry 포맷의 트레이스를 생성하고 내부 Durable Object에 저장합니다. 이 저장소를 Local Explorer API가 읽어 에이전트와 개발자가 조회할 수 있게 합니다.
workerd: — workerd는 Cloudflare Workers의 오픈소스 런타임으로, Fetch 호출·바인딩 접근·핸들러 수명주기 등 핵심 지점을 계측해 자동 스팬을 생성합니다. 별도 SDK나 코드 변경 없이 런타임 수준에서 스팬을 수집하는 것이 핵심이며, 이 계측 정보가 로컬 개발 시에도 동일하게 제공됩니다. 그 결과 개발자는 배포 전 로컬에서 상세한 추적 정보를 확인할 수 있습니다.

기술

OpenTelemetry
Wrangler
Miniflare
Cloudflare Vite plugin
D1
KV
R2
Durable Objects
Queues
workerd

활용 사례

코딩 에이전트가 로컬에서 에러를 재현하고 스팬 기반 텔레메트리로 실패 지점을 식별해 수정·검증하는 워크플로우
개발자가 배포 전에 로컬에서 특정 요청의 스팬과 콘솔 로그를 시각적으로 분석해 문제 원인을 좁히는 경우