사용자/제품 로그 설계

Polaris의 제품 funnel, 미션 품질, 별조각 정합성, AI 품질 저하를 운영 데이터로 확인하기 위한 문서입니다.

🗺️ 문서 이동

이전/다음 문서

← 이전	운영/모니터링 설계 개요
다음 →	인프라 모니터링 설계
전체	문서 지도

🎯 목적

사용자/제품 로그는 Polaris의 제품 개선, 사용자 행동 분석, 보상 정합성 추적, AI 품질 분석을 위한 데이터 기반이다.

MVP 단계에서는 외부 product analytics 도구를 바로 도입하기보다, 이미 백엔드에 존재하는 event_logs와 도메인 테이블을 우선 활용한다. 이를 통해 비용을 줄이고, Polaris의 핵심 흐름인 온보딩 → 캐릭터 생성 → 미션 제안 → 완료/거절 → 보상 → 공유/구매를 서비스 내부 데이터로 직접 분석한다.

이 문서에서 말하는 분석은 단순히 이벤트 수를 세는 것이 아니다. 사용자가 어디서 루틴 형성에 성공하거나 이탈하는지, 어떤 미션이 잘 받아들여지는지, 보상 구조가 동기부여로 작동하는지, AI fallback이 사용자 경험에 영향을 주는지 확인하는 것을 목표로 한다.

💡 왜 사용자/제품 로그를 우선 보는가

MVP 초반에는 트래픽보다 “사용자가 핵심 가치를 경험했는지”가 더 중요하다.

가입자가 있어도 온보딩에서 이탈하거나, 미션을 받기만 하고 완료하지 않거나, AI fallback이 늘어 개인화 품질이 떨어지면 서비스가 제대로 작동한다고 보기 어렵다.

또한 Polaris에는 별조각 보상처럼 사용자 신뢰와 연결되는 데이터가 있다. 제품 로그는 행동 흐름을 보여주고, 도메인 원장은 보상 정합성을 보여준다. 두 데이터를 함께 봐야 운영 중 문제가 생겼을 때 “무슨 일이 일어났는지”를 설명할 수 있다.

🧭 이 문서의 범위

구분 이 문서에서 다룸 상세 문서

제품 funnel	가입, 온보딩, 미션, 보상, 공유 흐름	이 문서
AI 품질 분석	fallback rate, error type, latency, 완료율 차이	이 문서
보상 정합성	별조각 지급/소비, 중복/누락 의심	이 문서
알림/장애 대응	임계치, 담당자, 대응 절차	Runbook
인프라/서버 상태	CPU, Docker, Redis, PostgreSQL health	인프라 모니터링
API/JVM 메트릭	HTTP latency, 5xx, JVM, Prometheus	애플리케이션 메트릭
Synthetic data	가상 사용자 생성, 부하/혼돈 실험	Synthetic Data

🧠 제품 로그로 답할 질문

영역 핵심 질문 주요 지표 개선 액션

👥 활성화	사용자가 가입 후 핵심 경험까지 도달하는가?	온보딩 완료율, 첫 미션 도달률, 첫 미션 완료율, D1/D7 retention	온보딩/홈/첫 미션 UX 개선
🧩 미션 품질	미션이 사용자에게 맞는가?	거절률, 완료율, 카테고리/난이도별 완료율, stack order별 이탈	추천 정책, seed/free generation, 질문 문구 개선
💫 별조각	보상 구조가 정상 작동하는가?	지급/소비량, reason별 분포, 잔액 분포, 중복 지급 의심	보상량/가격 조정, 멱등성 점검
🔗 공유	공유가 재방문/유입에 도움이 되는가?	공유 카드 생성 수, 공유 이벤트 수, 공유 보상 수령률, 공유 후 재방문율	공유 CTA, 보상 정책, 카드 UX 개선
🤖 AI 품질	AI 품질 저하가 제품 경험에 영향을 주는가?	fallback rate, error type, latency p95, fallback 여부별 완료율/거절률	프롬프트 개선, fallback copy 개선, provider/Redis 정책 조정

🧮 핵심 지표 정의

지표 정의 주요 데이터

신규 가입자 수	USER_SIGNED_UP 이벤트 수	event_logs
DAU	하루 동안 핵심 행동을 한 distinct user 수	event_logs
핵심 행동 사용자	미션/출석/공유/구매 중 하나 이상 수행한 사용자	event_logs
온보딩 완료율	온보딩 완료 사용자 / 신규 가입 사용자	event_logs, onboarding_profiles
첫 미션 도달률	첫 미션 제안을 받은 사용자 / 온보딩 완료 사용자	event_logs, user_missions
첫 미션 완료율	첫 미션을 완료한 사용자 / 첫 미션을 받은 사용자	user_missions
미션 거절률	MISSION_REJECTED / MISSION_OFFERED	event_logs
미션 완료율	MISSION_COMPLETED / MISSION_OFFERED	event_logs
완료 세션 이탈률	completion session started 후 completed가 없는 비율	event_logs, mission_completion_answers
AI fallback rate	fallback 요청 / 전체 AI 요청	ai_usage_logs, ai_mission_generations
Redis AI rate limit 장애 수	error_type = RATE_LIMIT_UNAVAILABLE 수	ai_usage_logs
일별 별조각 순증감	지급량 - 소비량	star_piece_transactions
공유 보상 수령률	reward paid share / share event	share_logs

🧭 현재 사용 가능한 데이터 소스

데이터 용도

event_logs	제품 이벤트 공통 로그, funnel/segment 분석
ai_usage_logs	AI 요청 상태, latency, error type, rate limit 장애
ai_mission_generations	AI 생성 결과, fallback 여부, prompt/model 추적
user_missions	미션 상태, 카테고리, 난이도, stack order
mission_completion_answers	완료 질문 진입/답변 제출 흐름
star_piece_transactions	별조각 지급/소비 원장
wallets	사용자별 현재 잔액
attendance_records	출석/재방문 분석
share_cards, share_logs	공유 카드 생성, 공유 이벤트, 보상 여부

📺 대시보드 구성

대시보드 주요 패널

🧭 제품 요약	DAU, 신규 가입자, 온보딩 완료율, 출석률, 미션 완료율
🧩 미션 품질	제안/거절/완료 funnel, 카테고리별 완료율, 난이도별 완료율
🤖 AI 품질	AI 성공/fallback 비율, error type 분포, latency p95, Redis unavailable
💫 별조각 정합성	지급/소비량, reason별 분포, 잔액 음수 여부, 중복 지급 의심
🔗 공유/상점	공유 카드 생성, 공유 이벤트, 공유 보상, 아이템 구매

🔍 분석 방법

1. Raw event 확인
2. 이벤트 누락, 타입 이름, user_id/ref_id/properties_json, 민감정보 포함 여부를 먼저 확인한다.
3. Daily aggregate 생성예: v_daily_user_activity, v_daily_mission_funnel, v_daily_ai_quality, v_daily_wallet_economy
4. 반복적으로 보는 지표는 Grafana query 또는 SQL view로 고정한다.
5. Funnel 분석현재 CHARACTER_CREATED 이벤트가 없으면 캐릭터 테이블 또는 API 성공 로그로 보완하고, 이후 이벤트 추가를 검토한다.
6. 대표 흐름은 USER_SIGNED_UP → ONBOARDING_COMPLETED → CHARACTER_CREATED → MISSION_OFFERED → MISSION_COMPLETED로 본다.
7. Cohort/Segment 분석미션은 카테고리, 난이도, stack order, 캐릭터 타입, AI fallback 여부로 나누어 본다.
8. 가입일, 온보딩 완료일, 첫 미션 완료 여부, 공유 여부 기준으로 retention을 본다.
9. Insight 작성
10. 숫자만 남기지 않고 발견한 현상 → 근거 지표 → 가능한 원인 → 추천 액션 → 다음 확인 지표 순서로 정리한다.

🛠️ 분석 결과를 어떻게 사용할 것인가

발견한 지표 해석 액션

온보딩 완료율 낮음	설문 길이/질문 이해도 문제 가능성	질문 수 축소, 진행률 표시, 중간 저장 UX 개선
첫 미션 완료율 낮음	첫 가치 경험이 약함	첫 미션 난이도 하향, 보상 강조, 캐릭터 코멘트 개선
특정 카테고리 거절률 높음	사용자 맥락과 미션 불일치	추천 조건 조정, seed/free generation prompt 개선
완료 세션 이탈률 높음	완료 질문이 부담스럽거나 UX가 불편	질문 문구 단순화, placeholder 개선
AI fallback rate 급증	provider/Redis/rate limit 문제 가능성	ai_usage_logs.error_type 확인, Runbook 연결
별조각 지급 급증	중복 지급 가능성	idempotency key, transaction count 확인
구매 전환율 낮음	아이템 매력/가격/노출 문제	가격 조정, 장착 preview 강화

📌 지표 해석 시 주의할 점

• 이벤트 수와 사용자 수를 구분한다. 미션 제안 100건은 사용자 100명을 의미하지 않는다.
• 초기 데이터는 표본이 작으므로 비율과 절대 건수를 함께 본다.
• 공유 사용자의 retention이 높아도 공유가 원인이라고 단정하지 않는다.
• event_logs는 제품 분석용이고, 별조각 정합성은 star_piece_transactions, share_logs, user_missions.idempotency_key 같은 도메인 원장을 기준으로 본다.
• AI fallback은 API 실패가 아니라 품질 저하 신호다. 5xx와 별도로 관측한다.

🧩 MVP 구현 우선순위

1. 👥 핵심 제품 흐름
2. 가입, 온보딩 완료, 미션 제안, 미션 완료, 미션 거절, 출석
3. 🤖 AI 품질/장애
4. fallback rate, error_type, RATE_LIMIT_UNAVAILABLE, latency
5. 💫 별조각 정합성
6. 지급량, 소비량, idempotency key, 잔액 음수, 중복 지급 의심
7. 🔗 공유/상점 고도화
8. 공유 카드 생성, 공유 이벤트, 공유 보상, 아이템 구매, 장착/사용

🗺️ 최종 운영 흐름

사용자 행동 발생
→ 도메인 트랜잭션 성공
→ event_logs / domain log table 저장
→ SQL 또는 Grafana query로 핵심 지표 계산
→ 팀이 제품/운영 이슈 발견
→ 개선 PR 또는 운영 조치
→ 다음 주 지표로 개선 효과 확인

로그는 쌓아두는 것이 아니라 다음 행동으로 이어져야 한다.

로그 수집 → 분석 → 가설 → 개선 → 검증

🔗 연결 문서

• 🚨 알림 임계치와 대응 절차는 Runbook에서 관리한다.
• 🧪 Synthetic data 입력값과 부하 시나리오는 Synthetic Data 문서에서 관리한다.
• 📈 API latency, 5xx, JVM 지표는 애플리케이션 메트릭 문서에서 관리한다.
• 🧯 프론트 runtime error와 API 실패는 프론트 에러 모니터링 문서에서 관리한다.

🗣️ 팀 논의 필요 항목

1. event_logs에 프론트 직접 이벤트를 넣을지 여부
2. 익명 사용자 anonymous_id를 프론트에서 생성할지 여부
3. 사용자 답변 전문을 분석 대상으로 사용할지, 길이/카테고리만 사용할지
4. 외부 analytics 도구를 MVP부터 붙일지 여부
5. 로그 보관 기간
6. Grafana 대시보드를 누가 관리할지
7. 운영 분석용 read-only DB 계정을 만들지 여부