성능 관련 문의 대응
고객이 성능 관련 문제를 신고할 때의 대응 가이드다. UI 화면 기준 증상 → 기술 원인 → 해결 경로 순으로 진행한다.
1. 증상 목록
| # | 고객이 말하는 증상 (UI 기준) | 섹션 |
|---|---|---|
| S-1 | "화면이 느립니다 / 로딩이 오래 걸립니다" | 2.1 |
| S-2 | "API 요청이 타임아웃됩니다" | 2.2 |
| S-3 | "서버 메모리 사용량이 너무 높습니다" | 2.3 |
2. 증상별 대응 가이드
2.1 S-1: 화면이 느리다
증상: 대시보드, 트랜잭션 익스플로러, 설정 화면 등에서 페이지 전환 또는 초기 로딩이 5초 이상 소요된다. 브라우저 Network 탭에서 TTFB(Time To First Byte)가 높다.
고객에게 확인
- 어떤 화면에서 느린가? (대시보드, 트랜잭션 익스플로러, 특정 설정 화면 등)
- 동시 접속자가 얼마나 되는가?
- 특정 시간대(업무 피크 등)에만 느린가?
- 최근 시스템 변경(배포, 설정 변경)이 있었는가?
기술지원 확인
- PM2 인스턴스 수 확인 (단일 프로세스 병목):
docker exec flowkat-ui-server pm2 list
# instances 수가 CPU 코어 수와 일치하는지 확인
- UI 서버 리소스 확인:
docker stats flowkat-ui-server --no-stream
# CPU %, MEM % 확인
- nginx 정적 파일 캐시 동작 확인:
curl -I http://localhost:6300/_next/static/chunks/main.js
# X-Cache-Status: HIT 여부 확인
- 네트워크 지연 확인:
curl -s -w "\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
-o /dev/null http://localhost:6300/
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| PM2 인스턴스 수 | CPU 코어 수 동일 | 1개 (단일 프로세스) |
| nginx 캐시 | X-Cache-Status: HIT | MISS 반복 |
| TTFB | < 500ms | > 2000ms |
| CPU 사용률 | < 70% | 90% 이상 |
벤더 에스컬레이션 시 전달 정보
-
docker exec flowkat-ui-server pm2 list출력 -
docker stats --no-stream출력 (전체 컨테이너) - nginx 설정 (
extra/nginx.conf)에서proxy_cache_path설정 유무 - 동시 접속자 수 및 느려지는 시간대
- 서버 사양 (CPU 코어 수, 메모리)
2.2 S-2: API 타임아웃
증상: 특정 API 요청이 수십 초 후 타임아웃되거나 브라우저에서 ERR_CONNECTION_TIMED_OUT 오류가 발생한다.
고객에게 확인
- 타임아웃되는 API는 무엇인가? (브라우저 Network 탭에서 확인)
- 특정 서비스나 서버 조회 시만 발생하는가?
- 트랜잭션 익스플로러 조회인 경우 조회 기간이 얼마나 긴가?
기술지원 확인
- nginx 타임아웃 설정 확인:
docker exec flowkat-ui-server grep -n "timeout" /etc/nginx/http.d/default.conf
# proxy_read_timeout, proxy_connect_timeout 값 확인
- API 서버 응답 시간 측정:
# API 서버 직접 호출 (nginx 우회)
time curl -s http://localhost:6600/api/flowkat/config/dashboard/list -o /dev/null
- DB 느린 쿼리 확인:
docker logs flowkat-api-server --tail 100 | grep -i "slow\|timeout\|exceed"
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| nginx proxy_read_timeout | 60초 이상 | 기본값 60초 미만 또는 누락 |
| API 직접 응답시간 | < 5초 | > 30초 |
| DB 연결 상태 | 정상 응답 | 연결 타임아웃 |
벤더 에스컬레이션 시 전달 정보
- 타임아웃 API의 URL 및 파라미터 전문
- 브라우저 Network 탭 캡처 (타임아웃 요청)
- nginx 타임아웃 설정값
-
time curl http://localhost:6600/api/...직접 호출 결과 - API 서버 로그 (타임아웃 발생 전후 5분)
2.3 S-3: 메모리 사용량 과다
증상: 서버 모니터링 툴 또는 docker stats에서 FlowKat 컨테이너의 메모리 사용량이 지속적으로 증가하거나 설정 한도에 근접한다.
고객에게 확인
- 어떤 컨테이너의 메모리가 높은가? (UI 서버, Dashboard 서버, 트랜잭션 익스플로러 등)
- 언제부터 높아지기 시작했는가? (배포 이후, 특정 기능 사용 이후 등)
- 재시작하면 낮아지는가?
기술지원 확인
# 전체 컨테이너 메모리 사용량 확인
docker stats --no-stream
# TX-Mining API 서버 JVM 힙 확인
docker exec flowkat-tx-mining-api jps -lv | grep -o "\-Xmx[^ ]*"
# Collect 서버 GC 로그 확인
docker logs flowkat-collect-server --tail 100 | grep -i "gc\|heap\|memory"
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| TX-Mining MEM% | < 70% | > 85% 또는 지속 증가 |
| JVM 힙 설정 | -Xmx2g 이상 | 소용량 힙 설정 |
| Collect 서버 GC | 정상 GC 로그 | Full GC 반복 또는 OOM |
벤더 에스컬레이션 시 전달 정보
-
docker stats --no-stream출력 (전체 컨테이너) - 메모리 과다 컨테이너의 JVM 옵션 (
jps -lv또는 서버 JVM 옵션) -
docker logs {container} --since 1h | grep -i "gc\|heap\|oom\|memory"출력 - 메모리 증가 시작 시점 및 관련 이벤트 (배포, 대량 조회 등)
3. 관련 문서
| 모듈 | 관련 trouble-shooting | 핵심 이슈 |
|---|---|---|
| nginx PM2 튜닝 | 004-nginx-pm2-performance-tuning | PM2 인스턴스, 캐시, keepalive |
| Collect 서버 GC | 065-collect-server-profiledelayingcache-gc-analysis | GC 분석, 캐시 최적화 |
| LRU 캐시 최적화 | 043-cache-optimization-lru-caffeine | Caffeine 캐시 설정 |