English {#english}
Cloudflare Logpush — Email Tracking and Workers Logs to R2
Purpose: Add Workers Trace Events (and optionally other datasets such as HTTP Requests) to the existing R2 bucket used for Logpush, so email-flow Workers (prego-auth-worker, pregoi-email-queue-gateway, pregoi-mail-sender) are logged and the email tracking/verification dashboard can query R2.
No code generation — plan, setup steps, datasets, destination only.
References: email-delivery-flow-verification-dashboard-plan; cloudflare-logpush-observability-plan; runbook logpush-setup.
1. R2 destination (existing)
Type: R2 Object Storage. Bucket: e.g. cloudflare-managed-* (account-specific). Custom R2 requires Access Key ID and Secret in destination_conf. Cloudflare-managed bucket may already have Logpush write permission.
2–4. Datasets, path layout, setup (summary)
- §2.1 Workers Trace Events (priority): Dataset
workers_trace_events. Use for request/response metadata, console.log, exceptions from Auth Worker, email-queue-gateway, mail-sender. Workers Paid plan required. Filter by ScriptName optional. No “email-only” dataset; email flow runs via Workers, so Workers logs = email-flow visibility; Resend result via Resend; Worker execution via R2 logs. - §2.2 HTTP Requests (optional): Zone-level; use if Zuplo sits behind a Zone. §2.3 Other: firewall_events, audit_logs, dns_logs as needed.
- §3 R2 path: dataset-specific prefix, e.g.
workers_trace_events/,http_requests/; use date placeholder for daily folders (e.g.workers_trace_events/2025-02-28/...). - §4 Setup: Create Job(s) in Logpush UI or API; destination_conf = R2 bucket + prefix; Workers Trace Events first; then HTTP Requests if Zone exists. See logpush-setup runbook.
Full tables (§1–§4) and exact wording are in the Korean section below.
한국어 {#korean}
Cloudflare Logpush — 이메일 트래킹·Workers 로그 R2 수집 기획서
목적: Cloudflare Logpush 설정 화면에서 사용 중인 R2 버킷을 목적지로 하여, Workers Trace Events 및 필요 시 기타 데이터셋(HTTP Requests 등)을 추가하는 방안을 정리한다. 이메일 전달 플로우 관련 Worker(prego-auth-worker, pregoi-email-queue-gateway, pregoi-mail-sender) 로그와, 추후 이메일 트래킹·검증 대시보드에서 R2 로그를 조회할 수 있도록 한다.
코드 생성 없음 — 기획·설정 절차·데이터셋·목적지만 명세.
참조:
- email-delivery-flow-verification-dashboard-plan.md — 이메일 플로우·플로우별 검증 대시보드 (R2 로그 조회 소스)
- cloudflare-logpush-observability-plan.md — 통합 로그 관측성 전략
- logpush-setup.md — Logpush Job 생성·조회·삭제 Runbook
1. R2 목적지 정보 (기존 설정)
Logpush 설정 화면에서 이미 지정한 R2 Object Storage 목적지는 아래와 같다.
| 항목 | 값 |
|---|---|
| 저장소 유형 | R2 Object Storage |
| 버킷 이름 | cloudflare-managed-f6a80c57 |
| S3 호환 엔드포인트 (예시) | https://3a555a2adb6585031cb8541ef5e6d2a0.r2.cloudflarestorage.com/cloudflare-managed-f6a80c57 |
| 계정 ID | 3a555a2adb6585031cb8541ef5e6d2a0 (URL에서 추출; kinybaik 계정) |
- Cloudflare 관리 버킷으로 생성된 경우, Logpush가 자동으로 해당 버킷에 쓰기 권한을 갖도록 설정되어 있을 수 있다.
- 커스텀 R2 버킷을 쓰는 경우에는 R2 API 토큰(Access Key ID, Secret Access Key)을 Logpush Job 생성 시
destination_conf에 넣어야 한다.
2. 추가할 Logpush 기능 (데이터셋)
2.1 Workers Trace Events (우선)
| 항목 | 내용 |
|---|---|
| 데이터셋 | workers_trace_events |
| 용도 | 이메일 플로우 관련 Worker의 요청/응답 메타데이터, console.log() 출력, 미처리 예외 수집. 이메일 트래킹·장애 확인 시 Auth Worker / Gateway / Mail Sender 로그로 활용. |
| 대상 Worker | prego-auth-worker, pregoi-email-queue-gateway, pregoi-mail-sender |
| 플랜 요건 | Workers Paid 플랜 필요 (Cloudflare 문서 기준). |
| 필드 예시 | Event, EventTimestampMs, Outcome, ScriptName, Logs (console 출력), Exceptions, Request, Response 등. (Cloudflare Logpush Workers 문서의 필드 목록 참고.) |
| 필터(선택) | ScriptName으로 특정 Worker만 수집 가능 (예: prego-auth-worker만). 전체 계정 Worker 로그를 받을 경우 필터 생략. |
이메일 트래킹과의 관계
- Cloudflare에는 “이메일 전용” Logpush 데이터셋은 없다.
- Prego 이메일 플로우는 Workers(Auth Worker가 Zuplo /email 호출, Gateway·Mail Sender가 Resend 연동)를 통해 이루어지므로, Workers Trace Events를 R2로 보내면 “이메일 관련 Worker 실행”을 로그로 추적할 수 있다.
- Resend 발송 결과는 Resend 대시보드/API로 확인하고, Worker 쪽 “요청이 Gateway까지 갔는지 / Consumer가 실행됐는지”는 R2에 쌓인 Workers 로그로 확인하는 구조가 적합하다.
2.2 HTTP Requests (선택)
| 항목 | 내용 |
|---|---|
| 데이터셋 | http_requests |
| 스코프 | Zone 단위. Prego/Zuplo가 프록시하는 Zone이 있을 때만 적용. |
| 용도 | 에지 HTTP 요청 로그(URL, 메서드, 상태 코드, 지연 등). Zuplo 앞단에 Cloudflare Zone이 있으면 해당 Zone에 대한 Logpush Job을 추가할 수 있음. |
| 참고 | Zone이 없거나 Zuplo만 직접 노출된 구조면 이 Job은 생략 가능. |
2.3 기타 데이터셋 (선택)
| 데이터셋 | 용도 | 비고 |
|---|---|---|
| firewall_events | WAF 차단·경고 | Zone + WAF 사용 시 |
| audit_logs | 계정/Zone 설정 변경 감사 | 계정 단위 |
| dns_logs | DNS 쿼리 로그 | Zone DNS 사용 시 |
이메일 트래킹·Workers 검증이 주 목적이면 Workers Trace Events 우선, 필요 시 HTTP Requests 등 추가.
3. R2 경로 구조 (제안)
동일 버킷 cloudflare-managed-f6a80c57 안에서 데이터셋별·일자별로 구분해 저장하면 이후 대시보드·스크립트에서 조회하기 쉽다.
| 데이터셋 | R2 prefix (예시) | 파일 경로 예 |
|---|---|---|
| Workers Trace Events | workers_trace_events/ | workers_trace_events/2025-02-28/... (날짜별 하위 디렉터리) |
| HTTP Requests | http_requests/ | http_requests/2025-02-28/... |
- Cloudflare Logpush Job 생성 시 destination_conf에서
{DATE}또는 이에 상응하는 날짜 치환자를 사용해 일별 폴더로 쌓이게 설정하는 것을 권장 (문서: Enable Cloudflare R2).
4. Logpush Job 설정 절차 (요약)
4.1 대시보드에서 추가
- Cloudflare Dashboard → 계정 선택 (kinybaik) → Logs → Logpush.
- Create a Logpush job 선택.
- Dataset:
Workers Trace Events선택. - Destination: R2 선택.
- 기존에 연결한 버킷이 Cloudflare 관리 버킷(
cloudflare-managed-f6a80c57)이면 해당 버킷 선택. - 커스텀 R2인 경우: S3 호환 API 기준으로 목적지 URL에 R2 Access Key ID, Secret Access Key를 포함한 형태로 설정 (Cloudflare 문서의
destination_conf예시 참고).
- 기존에 연결한 버킷이 Cloudflare 관리 버킷(
- 필드: 필요한 필드만 선택 (EventTimestampMs, ScriptName, Logs, Exceptions, Outcome, Request, Response 등). 전부 보내면 용량·비용 증가.
- 필터(선택): 특정 Worker만 수집 시
ScriptName조건 지정. - 저장 후 수 분 내 R2에
workers_trace_events/YYYY-MM-DD/형태로 파일이 생성되는지 확인.
4.2 API로 Job 생성 (자동화 시)
- Endpoint:
POST /accounts/{account_id}/logpush/jobs - Body 예시 (Workers Trace Events → R2):
dataset:"workers_trace_events"destination_conf: R2 S3 호환 경로.
예:r2://cloudflare-managed-f6a80c57/workers_trace_events/{DATE}?account-id=3a555a2adb6585031cb8541ef5e6d2a0&...
(Cloudflare 관리 버킷 사용 시 자동 인증일 수 있음; 커스텀 시access-key-id,secret-access-key등 파라미터 필요.)
- logpull_options:
fields에 포함할 필드 목록. - 상세 필드명·파라미터는 Cloudflare Logpush API, Workers Logpush 문서 참고.
5. 이메일 검증 대시보드와의 연동
- email-delivery-flow-verification-dashboard-plan.md에서 “Cloudflare Worker 로그” 소스로 Logpush → R2를 전제로 했다.
- R2 경로: 위와 같이
cloudflare-managed-f6a80c57버킷 내workers_trace_events/YYYY-MM-DD/(및 필요 시http_requests/...)에 로그가 쌓이면, 검증 대시보드 백엔드에서 다음을 수행할 수 있도록 설계한다.- 시간대·ScriptName으로 R2 객체 목록/내용 조회 (S3 API 호환).
- “마지막 검증 실행” 시각 전후의 Worker 로그만 필터해 플로우 A/B 단계별로 표시.
- 이메일 트래킹 관점에서는:
- Workers Trace Events: Auth Worker의 “[OTP] Sending email via Zuplo”, “[Zuplo email] 202 Accepted”, Gateway·Mail Sender의 console 로그로 “어느 단계까지 도달했는지” 확인.
- Resend: 발송 성공/실패는 Resend API·대시보드로 확인하고, 대시보드에서는 “Worker 로그 + Resend 로그”를 함께 보여 주는 구조를 기획서에 반영할 수 있다.
6. 체크리스트 (구현 전 확인)
| 항목 | 확인 내용 |
|---|---|
| R2 버킷 | cloudflare-managed-f6a80c57 가 해당 계정(3a555a2adb6585031cb8541ef5e6d2a0)에 존재하는지, Logpush가 쓰기 가능한지 확인. |
| Workers 플랜 | Workers Trace Events Logpush 사용을 위해 Workers Paid 이상인지 확인. |
| destination_conf | Cloudflare 관리 버킷인지·커스텀인지에 따라 destination_conf에 필요한 쿼리 파라미터(account-id, access-key-id, secret-access-key 등)가 문서와 일치하는지 확인. |
| 필드·필터 | 수집할 필드와(선택) ScriptName 필터를 정해 두면 비용·노이즈를 줄일 수 있음. |
| 보존 기간 | R2 Lifecycle 규칙으로 오래된 prefix(예: 90일 경과) 자동 삭제 여부 결정. |
7. 구현 이력
| 항목 | 내용 |
|---|---|
| Logpush Job 생성 | infra/logpush_setup.ts: 데이터셋별 필드·경로 기본값, create-all-email-workers 서브커맨드, --script-name 필터 지원. 버킷 cloudflare-managed-f6a80c57 기준. |
| Runbook | logpush-setup.md: §1b 이메일·Workers 로그, create-all-email-workers 및 단일 Job 생성 예시, §5 Lifecycle 보존 기간. |
| R2 Lifecycle | Runbook §5: 대시보드·Wrangler·API 절차. infra/logpush_r2_lifecycle_example.json: prefix workers_trace_events/, http_requests/, edge/ 각 90일 만료 규칙 예시. |