techlist.io
KREN
cloudflare

이제 에이전트가 로컬 트레이싱으로 Workers를 디버깅할 수 있습니다 (새 탭에서 열림)

observabilitycloudflare-workersdurable-objectssqliteopentelemetrywranglerviteminiflare

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 스키마를 제공하므로, 에이전트가 사전에 하드코딩된 지침 없이 실행 중 사용 가능한 엔드포인트를 탐색할 수 있습니다.

  • 트레이스와 연결된 콘솔 로그는 다음과 같은 읽기 전용 엔드포인트로 조회할 수 있습니다.

    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 기반 프로젝트:

    npm install --save-dev wrangler@latest

  • Cloudflare Vite 플러그인 기반 프로젝트:

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

업데이트 후 평소처럼 wrangler dev 또는 vite dev를 실행하고, 에이전트에게 로컬에서 오류를 재현하고 수정한 뒤 검증하도록 요청하면 됩니다. 로컬 트레이스를 활용하면 배포 전에 실패한 바인딩 호출과 환경 문제를 빠르게 찾아 수정할 수 있으므로, Cloudflare Worker 프로젝트의 에이전트 기반 디버깅에서는 최신 Wrangler 또는 Vite 플러그인 사용을 권장합니다.