English {#english}
Cloudflare Logpush Observability Plan
Purpose: Define centralized log management for Prego (multi-tenant, multi-node): collect logs via Cloudflare Logpush and R2 for observability, security, and audit.
No code generation — plan, architecture, roadmap, operations only.
References: cloudflare-orchestration-and-gtape-backup-plan; provision-tenant-workflow-design §7.1; saas-db-separation-and-scaling-plan; worker-ai-implementation-plan; rag-ai-edge-architecture-plan; font-r2-and-local-setup; i18n-login-page-plan.
1. Background
Distributed logs are hard to aggregate manually. Need real-time dashboards and alerts; security and audit (PDPA/GDPR). Prego already uses R2, Workers, Zuplo, D1 — using R2 as Logpush destination unifies storage and avoids egress cost.
2–4. Architecture, Golden Signals, roadmap
- §2 Pipeline: Sources: Edge (Cloudflare), App (Frappe/Docker), DB (MariaDB). Docker: json-file driver, max-size/max-file, labels (tenant_id). Logpush: Jobs to R2, <1 min delay; filter by hostname; fields and rfc3339 timestamps. Destination: R2 (prego-logs/edge/, app/); optional Datadog/ELK. Usage vs observability: usage stays existing; logs unified here.
- §3 Golden Signals: Errors (5xx, Worker, traceback), Latency (TTFB, slow query), Traffic (RPS), Security (WAF, auth failures).
- §4 Roadmap: Phase 1 — R2 bucket, Logpush Jobs, Docker daemon.json. Phase 2 — JSON format, tenant_id, common fields, X-Request-ID. Phase 3 — dashboards, alerts, audit; Workers Cron for R2 analysis and 5xx Slack.
5–8. Operations, integration, summary, deliverables
- §5: Sampling (200 OK sampled; 4xx/5xx and security 100%). PII masking before store. R2 Lifecycle (30/90 days); audit logs separate. X-Request-ID (correlation ID) from Worker to origin for edge–app correlation. Workers Cron: R2 log analysis → Slack; optional daily report, Grafana/Datadog.
- §6–§7: Links to provision-tenant-workflow-design, saas-db-separation, cloudflare-orchestration, intelligent-automation, font-r2, i18n-login. Summary: Logpush + R2, Golden Signals, sampling, TTL, PII, X-Request-ID.
- §8 Phase 1 deliverables: R2 bucket (prego-pulumi), logpush_setup.ts (create/list/delete Jobs), runbook logpush-setup.
Full tables (§1–§8) and exact wording are in the Korean section below.
한국어 {#korean}
Cloudflare Logpush 기반 통합 로그 관측성(Observability) 체계 기획서
목적: 수백 명 규모의 테넌트가 여러 노드에 분산된 Prego 환경에서 발생하는 로그를 Cloudflare Logpush와 R2 중심으로 한곳에 모아, 가시성(Observability)·보안·감사(Audit)를 확보하는 중앙 집중형 로그 관리 전략을 정의한다.
코드 생성 없음 — 기획·아키텍처·로드맵·운영 전략만 정리.
참조:
1. 배경 및 필요성
| 항목 | 내용 |
|---|
| 분산 환경의 한계 | 멀티테넌트 아키텍처에서 각 App 서버·DB 서버·에지(Workers)에 흩어진 로그를 수동으로 모으고 분석하는 것은 불가능에 가깝다. |
| 실시간 대응 체계 | 에지 단계의 공격·애플리케이션 오류·특정 테넌트 장애를 즉시 탐지하고 대응할 수 있는 통합 대시보드·알람이 필요하다. |
| 보안 및 감사(Audit) | 테넌트별 데이터 접근·API 호출·인증 실패 기록을 중앙에서 영구 보존하여 컴플라이언스(PDPA·GDPR 등) 요구사항을 충족해야 한다. |
| 현행 Prego와의 정합성 | 이미 R2(usage_raw, 백업, static 등)·Workers(tenant-router, control-plane 등)·Zuplo·D1을 사용 중이므로, Logpush 목적지로 R2를 쓰면 Egress 비용 없이 저장·분석 파이프라인을 일원화할 수 있다. |
2. 시스템 아키텍처 (Log Pipeline)
2.1 로그 수집 레이어 (Data Source)
| 소스 | 설명 | Prego 적용 |
|---|
| Edge Logs (Cloudflare) | HTTP 요청 로그, WAF 차단, Worker 실행 로그를 Cloudflare에서 직접 추출. | tenant-router·control-plane·usage-writer 등 Workers 트래픽; *.pregoi.com 도메인. |
| App Logs (Frappe/ERPNext) | Docker 컨테이너 내 Python/Gunicorn·Nginx 로그. | 각 노드(Hetzner)의 Frappe bench 로그; 테넌트별 site는 canonical hostname 또는 X-Frappe-Site-Name으로 식별. |
| DB Logs (MariaDB) | Slow Query Log, 감사 로그(선택). | DB 서버 분리 시 saas-db-separation-and-scaling-plan.md 상의 DB 서버에서 수집. |
수집 방식 요약
- Edge: Cloudflare Logpush Job으로 에지 로그를 지정 저장소로 푸시(지연 1분 미만 수준 목표).
- App/DB: 호스트의
journald·파일·에이전트 등으로 먼저 모은 뒤, 별도 파이프라인(스크립트·Logpush 호환 엔드포인트 등)으로 전송. 구체 방식은 구현 단계에서 정의.
2.2 Docker 로그 구조화 (JSON 포맷)
로그를 “분석 가능한 데이터”로 가공하여 에지와 오리진(서버) 로그를 나중에 동기화·연관 짓기 위한 전략이다.
| 항목 | 내용 |
|---|
| 목적 | Docker 기본 텍스트 로그를 **구조화(JSON)**하여 파싱·필터·테넌트별 추적이 가능하게 한다. 호스트 디렉터리에 저장한 뒤 외부(R2·SIEM 등)로 전송할 준비를 한다. |
| Docker Daemon | /etc/docker/daemon.json에서 log-driver: json-file을 모든 컨테이너 공통 기본값으로 둔다. log-opts로 max-size(예: 100m), max-file(예: 3)을 설정해 로그 파일 하나가 과대해지지 않게 하고 디스크 풀(Full) 장애를 방지한다(Defensive Engineering). 선택적으로 labels, env를 로그 메타데이터로 포함해 테넌트·앱 이름으로 필터링 가능하게 한다. |
| Docker Compose | Frappe App 등 특정 서비스에는 logging.driver: json-file, logging.options에 labels로 tenant_id(또는 app_name)를 부여한다. 컨테이너별로 테넌트 라벨이 붙어 나중에 테넌트별 로그 필터링·비용 산정에 활용한다. |
| 구현 위치 | Ansible(또는 프로비저닝)에서 daemon.json 배포; Compose 템플릿에서 logging 블록 정의. 기획만 하고 코드는 구현 단계에서 작성. |
2.3 로그 전송 레이어 (Logpush)
| 항목 | 내용 |
|---|
| Cloudflare Logpush | 에지에서 발생한 로그를 1분 미만 지연으로 목적지(R2 등)에 푸시. |
| Job 설정 | 데이터셋(HTTP Requests, Workers, WAF 등)별 Job 생성. 필요 시 필터(예: hostname *pregoi.com)로 테넌트·도메인 그룹화. 목적지는 R2 버킷(S3 호환 API) 사용 시 Egress 비용 없어 대용량 로그 전송에 유리하다. |
| logpull_options 권장 | Job 생성 시 fields로 ClientIP, ClientRequestHost, ClientRequestMethod, EdgeResponseStatus, OriginResponseTime, EdgeResponseBytes 등 분석에 필요한 필드만 포함하고, timestamps는 rfc3339로 통일해 에지·앱 로그 간 시간 정렬·상관 분석을 쉽게 한다. |
| 연동 | 계정(Account) 또는 Zone 단위 Job; 구현 스크립트·Runbook은 logpush-setup.md 참조. |
2.4 로그 저장 및 분석 레이어 (Destination)
| 레이어 | 옵션 | 용도 |
|---|
| 저장소 | Cloudflare R2 | 장기 보관·비용 최소화(Egress 무료). 버킷 또는 prefix 예: prego-logs/edge/, prego-logs/app/. |
| 분석·시각화 | Datadog / New Relic | 실시간 대시보드·알람·온콜(Slack/PagerDuty) 연동. |
| 분석·시각화 | ELK Stack (Elasticsearch, Logstash, Kibana) | 상세 쿼리·디버깅·자체 호스팅 제어. |
| 기존 파이프라인 | R2 usage_raw, D1 집계 | prego-saas-control-platform-v4-implementation-plan.md §9.6 등과 역할 구분: Usage 메터링은 기존 그대로, 관측성·감사용 로그는 본 Logpush 체계로 일원화. |
3. 핵심 관리 지표 (Golden Signals)
구글 SRE의 Golden Signals를 기준으로, 실시간 모니터링·알람에 사용할 지표를 정리한다.
| 지표 (Metric) | 수집 대상 | 관리 목적 |
|---|
| 에러율 (Errors) | HTTP 5xx, Worker 예외, Python Traceback | 시스템 결함·코드 오류 즉시 탐지, 테넌트별 에러 추이. |
| 지연 시간 (Latency) | TTFB, Slow Query Log | 특정 테넌트·기능의 성능 저하 모니터링; font-r2-and-local-setup.md·i18n-login-page-plan.md의 지역별·언어별 지연·에러 분석과 연동. |
| 트래픽 (Traffic) | RPS (Requests Per Second), 요청 수 | 서비스 이용량 급증·DDoS·비정상 트래픽 감지. |
| 보안 (Security) | WAF Block, 인증 실패(Auth Failures), 의심 스캔 | 무단 접근·인젝션 시도 방어·감사. |
4. 단계별 구축 로드맵
Phase 1: 인프라 설정 (목표 1~2주)
| 작업 | 내용 |
|---|
| R2 버킷(또는 전용 prefix) | Logpush 전용 버킷 또는 prego-logs 등 prefix 생성. Lifecycle·접근 정책 설계. |
| Logpush Job 활성화 | Cloudflare 대시보드 또는 API로 Edge 데이터셋(HTTP Requests 등)에 대한 Logpush Job 생성, 목적지 R2 연결. |
| App/DB 로그 수집 기반 | Docker 컨테이너 로그를 호스트의 journald 또는 공통 로그 파일로 모으는 방식 결정. Docker daemon.json에서 json-file 드라이버·max-size/max-file·labels 설정으로 구조화 준비(§2.2). (구현은 별도.) |
Phase 2: 로그 표준화 (목표 2~3주)
| 작업 | 내용 |
|---|
| 포맷 통일 | 가능한 모든 로그를 JSON으로 통일해 파싱·집계 효율화. Docker Compose logging.options.labels로 tenant_id·app_name 부여(§2.2). |
| 테넌트 식별 | 로그 레코드(또는 헤더)에 tenant_id 또는 canonical hostname(tenant-{short_id}.pregoi.com) 주입. 테넌트별 비용 산정·문제 추적·감사 가능. |
| 필드 명세 | 타임스탬프·severity·message·tenant_id·host·path·status 등 공통 필드 정의. X-Request-ID(Correlation ID)로 에지–앱 로그 연관(§5.4). (문서화만, 코드 없음.) |
Phase 3: 시각화 및 자동 알람 (목표 3~4주)
| 작업 | 내용 |
|---|
| 대시보드 | 테넌트별·전체 트래픽·에러율·지연 시간 대시보드 구축. (Datadog/New Relic/Kibana 등 선택.) |
| 알람·온콜 | 임계치 초과 시 Slack·PagerDuty 등으로 엔지니어 호출(On-call) 연동. Workers Cron으로 R2 로그 분석·5xx 패턴 시 Slack 알림(§5.5). |
| 감사 조회 | 보안·컴플라이언스용 조회 절차·보존 기간 정책 문서화. |
| 후속 옵션 | Workers Cron으로 일일 트래픽 보고서 자동 생성; JSON 로그를 Grafana·Datadog으로 포워딩하는 파이프라인(§5.5). |
5. 운영 전략 (Principal Engineer 인사이트)
5.1 비용 최적화 — 샘플링(Sampling)
| 원칙 | 내용 |
|---|
| 전략 | 모든 로그를 100% 저장하면 비용이 급증한다. 정상 200 OK는 샘플링(예: 10%)하고, 4xx/5xx 에러와 보안 관련 로그(WAF Block, Auth Failures)는 100% 수집한다. |
| 적용 | Logpush 필터·Job별 설정 또는 수집 단계에서 샘플링 정책 적용. (구현 시 상세 정의.) |
5.2 데이터 마스킹 — PII 보호
5.3 로그 보존 정책 — TTL·Lifecycle
| 원칙 | 내용 |
|---|
| R2 Lifecycle | 로그는 시간이 지나면 가치가 떨어진다. R2 버킷에 Lifecycle 규칙을 두어, 30일 또는 90일 등 정책에 따라 경과한 상세 로그는 자동 삭제 또는 저비용 스토리지로 이동하여 비용·기술 부채를 방지한다. |
| 감사 로그 | 규제상 보존 의무가 있는 감사 로그는 별도 prefix·정책으로 장기 보존. rag-ai-edge-architecture-plan.md의 PDPA·보관 제한·자동 파기와 정합성 유지. |
5.4 로그 동기화 — Correlation ID (관측성 핵심)
| 원칙 | 내용 |
|---|
| X-Request-ID | Cloudflare Worker(tenant-router 등)에서 오리진으로 요청을 보낼 때 X-Request-ID(또는 동일 용도의 Correlation ID) 헤더를 생성해 전달한다. Docker 앱(Frappe) 로그에도 이 ID를 남기면, 에지 로그와 앱 로그를 하나의 타임라인으로 묶어 한 요청의 전 구간 추적이 가능하다(Observability 핵심). |
| 적용 | Worker 구현 시 요청마다 UUID 등 고유 ID 생성 후 헤더 주입; 앱·미들웨어에서는 해당 헤더를 읽어 로그 필드에 포함. cloudflare-orchestration-and-gtape-backup-plan.md §2.1의 X-Frappe-Site-Name 주입과 함께 적용. |
5.5 에러 감지 자동화 (다음 단계 권장)
| 항목 | 내용 |
|---|
| R2 로그 분석 | R2에 쌓인 로그를 주기적으로 읽어 5xx 또는 특정 에러 패턴이 발견되면 Slack(또는 PagerDuty) 알림을 보내는 자동화를 둔다. |
| 실행 주체 | Cloudflare Workers Cron Triggers로 R2(또는 Wrangler R2 바인딩)에서 최근 로그를 조회·파싱 후 임계치 초과 시 웹훅으로 알림 전송. Phase 3(시각화·알람)의 구체 수단으로 권장. |
| 확장 | 동일 Cron으로 일일 트래픽 보고서 자동 생성, 또는 수집된 JSON 로그를 Grafana·Datadog으로 포워딩하는 파이프라인 구성이 후속 과제로 적합하다. |
6. 기존 기획서와의 연동
| 문서 | 연동 내용 |
|---|
| provision-tenant-workflow-design.md §7.1 | 로그 통합 전략의 구체화. 본 기획서가 Logpush·R2·Golden Signals·Phase를 담당. |
| saas-db-separation-and-scaling-plan.md | 확장성 관리의 “로그 통합” 항목 → 본 기획서 참조로 일원화. |
| cloudflare-orchestration-and-gtape-backup-plan.md | Workers·Tunnel·R2와 동일 스택; Logpush는 에지·앱 로그를 R2로 모으는 수단. |
| intelligent-automation-implementation-plan.md | 모니터링 수집·D1 server_metrics와 역할 구분: 메트릭은 기존 경로, 로그는 Logpush 파이프라인. |
| font-r2-and-local-setup.md §Logpush | 폰트 요청 응답 시간·캐시 적중률 측정을 본 Logpush 체계의 한 사용 사례로 통합. |
| i18n-login-page-plan.md §12.1 | 국가별 접속·언어 불일치·아랍어 권역 에러 분석을 Logpush/R2 데이터로 수행. |
7. 요약 및 다음 단계
- 목표: 분산된 테넌트·노드·에지 로그를 Cloudflare Logpush + R2 중심으로 한곳에 모아, Golden Signals(에러·지연·트래픽·보안) 기반 관측성·알람·감사를 확보한다.
- 원칙: 데이터 유실 최소화(에러·보안 100%), 비용 제어(샘플링·TTL), PII 마스킹·보존 정책 준수.
- 다음 단계(구현 시):
- R2 버킷·Logpush Job 연결은 Phase 1 구현 완료.
- Docker daemon.json(json-file, max-size·max-file·labels) 및 Compose logging으로 앱 로그 구조화.
- X-Request-ID Worker·앱 연동으로 에지–오리진 로그 상관 분석.
- Workers Cron으로 R2 로그 분석·5xx 알람(Slack)·일일 보고서 또는 Grafana/Datadog 포워딩 파이프라인.
8. 구현 산출물 (Phase 1)
| 산출물 | 경로 | 설명 |
|---|
| R2 버킷 | prego-pulumi __main__.py | prego-logs 버킷 생성. r2_logs_bucket_name export. |
| Logpush Job 설정 스크립트 | infra/logpush_setup.ts | create / list / delete. R2 목적지로 에지 로그(HTTP Requests 등) 푸시 Job 생성. Env: CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY. |
| Runbook | docs/runbook/logpush-setup.md | 환경 변수·생성/조회/삭제 절차·Lifecycle·문제 해결. |
본 기획서는 기획·아키텍처·로드맵·운영 전략을 다룬다. Phase 2(로그 표준화·tenant_id 주입)·Phase 3(시각화·알람) 및 App/DB 로그 수집 방식은 별도 구현.
