이제 에이전트가 로컬 트레이싱으로 Workers를 디버깅할 수 있습니다 (새 탭에서 열림)
`wrangler dev`와 `vite dev`가 로컬 Worker 실행 중 OpenTelemetry 트레이스를 자동 수집해, 코딩 에이전트가 배포 전 오류 원인을 직접 분석하고 수정 결과를 검증할 수 있게 되었습니다. 별도의 SDK 설치, 트레이싱 설정, 에이전트 구성 없이도 에이전트 세션이 감지되면 Local Explorer API가 자동으로 안내됩니다. 에이전트는 트레이스와 로그뿐 아니라 로컬 바인딩 및 데이터 상태까지 조회해 디버깅할 수 있습니다. ## 로컬 Worker 실행 시 자동 트레이싱 - `wrangler dev` 또는 `vite dev`로 실행한 Worker 호출이 자동으로 OpenTelemetry 트레이스로 기록됩니다. - 별도의 SDK나 애플리케이션 코드 수정, 관측성 활성화 설정이 필요하지 않습니다. - Wrangler와 Cloudflare Vite 플러그인은 Miniflare를 통해 Worker를 로컬에서 실행하므로, 실제 Worker 런타임에 내장된 계측 기능을 로컬에서도 사용할 수 있습니다. - 에이전트 세션이 감지되면 개발 서버가 Local Explorer API 주소와 트레이스 조회 엔드포인트를 출력합니다. ## 에이전트가 자동으로 발견하는 Local Explorer API - Local Explorer는 로컬 리소스 데이터와 관측성 데이터를 확인할 수 있는 브라우저 UI이자 REST API입니다. - API 루트에서 OpenAPI 스키마를 제공하므로, 에이전트가 사전에 하드코딩된 지침 없이 실행 중 사용 가능한 엔드포인트를 탐색할 수 있습니다. - 트레이스와 연결된 콘솔 로그는 다음과 같은 읽기 전용 엔드포인트로 조회할 수 있습니다. ```text POST /cdn-cgi/explorer/api/local/observability/query ``` - 에이전트는 트레이스 조회 후 KV, D1, R2, Durable Objects, Workflows 등 로컬 바인딩과 저장 상태도 함께 검사할 수 있습니다. - Local Explorer는 Cloudflare 대시보드가 아니라 Worker와 같은 localhost에서 실행됩니다. - Wrangler에서 `e` 키 입력 - 또는 `/cdn-cgi/explorer` 접속 ## 트레이스로 오류 원인 식별 및 검증 예를 들어 `POST /api/orders`가 다음 작업을 수행한다고 가정합니다. - KV에서 활성 장바구니 조회 - D1에 결제 정보 저장 - Queue에 주문 처리 메시지 전송 스키마 변경 이후 요청이 500 오류를 반환하면 다음과 같이 분석할 수 있습니다. - 트레이스가 없을 때 - 500 응답만으로는 KV, D1, Queue 중 어디서 실패했는지 알기 어렵습니다. - 에이전트가 각 작업 전후에 임시 로그를 추가하고 요청을 반복 실행해야 합니다. - 로그 확인과 코드 수정이 반복되어 시간과 토큰이 소모됩니다. - 트레이스가 있을 때 - KV 조회는 성공했고, D1 삽입 단계에서 `no such column: delivery_window` 오류가 발생했다는 사실을 확인합니다. - D1 작업이 실패했기 때문에 Queue 호출까지 도달하지 않았다는 흐름도 파악할 수 있습니다. - 에이전트가 로컬 D1 스키마를 검사해 저장소에 존재하지만 아직 적용되지 않은 마이그레이션을 발견합니다. - 마이그레이션을 적용한 뒤 요청을 다시 보내고, 새 트레이스에서 성공 여부를 검증합니다. 이 과정은 임시 로그를 추가하거나 배포하지 않고도 오류 위치 확인, 환경 수정, 재검증을 한 번의 로컬 디버깅 루프에서 수행하게 해줍니다. ## 자동으로 기록되는 트레이스 범위 Worker 런타임인 `workerd`에 계측 기능이 내장되어 있어 다음 작업이 자동 기록됩니다. - **Fetch 호출** - 외부 HTTP 요청의 실행 시간 - 상태 코드 - 요청 관련 메타데이터 - **바인딩 호출** - KV, R2, D1, Durable Objects, Queues 등 Cloudflare 바인딩과의 상호작용 - **핸들러 호출** - `fetch`, `scheduled`, Queue 핸들러 등 호출 전체 생명주기 - 애플리케이션이 직접 생성한 커스텀 span도 자동 트레이스에 포함됩니다. - Miniflare는 런타임 이벤트와 콘솔 출력을 수집해 OpenTelemetry 트레이스 및 연결된 로그로 구성합니다. - 수집된 데이터는 내부 SQLite 기반 Durable Object에 저장되고, Local Explorer API를 통해 제공됩니다. ## 사람이 확인하는 Local Explorer - 에이전트는 REST API로 데이터를 조회하지만, 개발자는 브라우저 UI에서 동일한 정보를 시각적으로 확인할 수 있습니다. - 특정 요청을 선택하면 다음 정보를 볼 수 있습니다. - 전체 span 구조 - 각 작업의 실행 시간 - 속성 및 메타데이터 - 오류 정보 - 관련 콘솔 로그 - 로컬 바인딩 상태를 탐색하면서 요청 처리 흐름과 데이터 상태를 함께 점검할 수 있습니다. ## 사용 방법 - Wrangler 기반 프로젝트: ```bash npm install --save-dev wrangler@latest ``` - Cloudflare Vite 플러그인 기반 프로젝트: ```bash npm install --save-dev @cloudflare/vite-plugin@latest ``` 업데이트 후 평소처럼 `wrangler dev` 또는 `vite dev`를 실행하고, 에이전트에게 로컬에서 오류를 재현하고 수정한 뒤 검증하도록 요청하면 됩니다. 로컬 트레이스를 활용하면 배포 전에 실패한 바인딩 호출과 환경 문제를 빠르게 찾아 수정할 수 있으므로, Cloudflare Worker 프로젝트의 에이전트 기반 디버깅에서는 최신 Wrangler 또는 Vite 플러그인 사용을 권장합니다.