PerfKit - 성능 모니터링 플랫폼

웹 서비스의 핵심 성능 지표인 Web Vitals(LCP, CLS, FID)를 수집하고, 대시보드에서 쉽게 확인할 수 있도록 만든 모니터링 플랫폼입니다.

🚀 시작하는 방법

1. 의존성 설치

pnpm install

2. SDK 빌드

cd packages/sdk
pnpm build
cd ../..

3. 서비스 실행

방법 1: Turbo로 전체 앱 실행

pnpm dev

아래 세 가지가 동시에 실행됩니다:

• Collector 서버 (4000번 포트)
• Dashboard (3000번 포트)
• Example Web (3001번 포트)

방법 2: 개별 실행

Collector 서버

cd apps/collector
pnpm dev

→ http://localhost:4000에서 실행

Dashboard

cd apps/dashboard
pnpm dev

→ http://localhost:3000에서 확인 가능

Example Web (SDK 테스트용)

cd apps/example-web
pnpm dev

→ http://localhost:3001에서 실행

✅ 동작 확인하기

1. Collector 서버 확인

curl http://localhost:4000/api/metrics/lcp-average

처음에는 {"data":[]}처럼 빈 응답이 반환됩니다.

2. 데이터 수집 확인

1. Example Web 접속 → http://localhost:3001
2. 페이지 새로고침 또는 스크롤 등 사용자 행동을 몇 번 수행
3. 브라우저 Network 탭에서 /collect 요청이 발생하는지 확인

3. Dashboard에서 그래프 확인

1. Dashboard 접속 → http://localhost:3000
2. 서비스별 LCP 평균 그래프 확인
3. 수집된 데이터가 없다면 "데이터가 없습니다" 메시지가 표시됩니다

4. SQLite 데이터 직접 조회

cd apps/collector
sqlite3 perfkit.db

.tables
SELECT * FROM metrics ORDER BY timestamp DESC LIMIT 10;
SELECT service_id, name, value, timestamp FROM metrics WHERE name = 'LCP' ORDER BY timestamp DESC LIMIT 10;

.quit

📊 데이터 흐름 구조

브라우저
  ↓ Web Vitals 측정
SDK
  ↓ POST /collect
Collector 서버
  ↓ SQLite 저장
Database
  ↑ GET /api/metrics/lcp-average
Dashboard
  ↑ 그래프 시각화
사용자

🔧 환경 변수 설정

Dashboard

.env.local(선택)

NEXT_PUBLIC_COLLECTOR_URL=http://localhost:4000

Example Web

.env.local(선택)

NEXT_PUBLIC_COLLECTOR_URL=http://localhost:4000

둘 다 기본값은 http://localhost:4000입니다.

🐛 문제 해결 가이드

SDK 요청이 수집되지 않을 때

• Console 탭에서 에러 메시지 확인
• Network 탭에서 /collect 요청 상태 확인
• Collector 서버 실행 여부 확인

Dashboard에 데이터가 비어 있을 때

• Collector 서버가 정상 실행 중인지 확인
• Dashboard에서 API 요청이 성공했는지 Network 탭 확인
• SQLite에 데이터가 저장되어 있는지 조회

포트 충돌 시

• Collector: 4000
• Dashboard: 3000
• Example Web: 3001

이미 사용 중이라면 각 앱 설정에서 포트를 조정하세요.