로그 수집 방법

벤더 에스컬레이션 또는 장애 진단 시 수집해야 하는 로그 목록이다. 서비스별 수집 명령, 주요 확인 포인트, 헬스체크 스크립트를 정리한다.

---

1. Docker 서비스 로그

기본 수집 명령

각 컨테이너의 최근 500줄 로그를 수집한다.

# 전체 서비스 상태 확인
docker compose ps -a

# 개별 서비스 로그 (최근 500줄)
docker logs --tail=500 flowkat-collect-server  2>&1 | tee collect-server.log
docker logs --tail=500 flowkat-api-server       2>&1 | tee api-server.log
docker logs --tail=500 flowkat-dashboard-server 2>&1 | tee dashboard-server.log
docker logs --tail=500 flowkat-ui-server        2>&1 | tee ui-server.log
docker logs --tail=500 flowkat-tx-mining-api    2>&1 | tee mining-server.log
docker logs --tail=500 flowkat-valkey           2>&1 | tee valkey.log
docker logs --tail=500 flowkat-postgres-txmining 2>&1 | tee postgres.log

서비스별 주요 확인 포인트

서비스	컨테이너명	주요 확인 포인트	에러 키워드
collect-server	flowkat-collect-server	에이전트 연결, 플러그인 초기화, 메모리 사용	WARN, ERROR, OOM, Connection refused
api-server	flowkat-api-server	REST API 에러, DB 조회 실패	ERROR, 500, NullPointer
dashboard-server	flowkat-dashboard-server	H2 DB 오류, api-server 연결, 설정 로드	ERROR, H2, ECONNREFUSED
ui-server	flowkat-ui-server	Next.js 렌더링 에러, PM2 재시작	Error, ECONNREFUSED, pm2
tx-mining-api	flowkat-tx-mining-api	OOM, 쿼리 타임아웃, Valkey/PostgreSQL 연결	OOM, timeout, Connection refused
valkey	flowkat-valkey	메모리 부족, RDB/AOF 오류	ERR, OOM, WRONGTYPE
postgres	flowkat-postgres-txmining	연결 거부, 파티션 오류, 디스크 부족	FATAL, ERROR, no space left

시간 범위 지정 수집

# 특정 시간 이후 로그 (예: 2026-03-19 10:00 이후)
docker logs --since="2026-03-19T10:00:00" flowkat-collect-server 2>&1

# 최근 1시간 로그
docker logs --since=1h flowkat-collect-server 2>&1

---

2. 볼륨 내 로그 파일

Docker 로그와 별도로 컨테이너 볼륨에 기록되는 로그 파일이다.

collect-server 로그 파일

# 볼륨 경로: volumes/collect-server/logs/
ls -la volumes/collect-server/logs/

# 최신 로그 파일 확인
tail -200 volumes/collect-server/logs/*.log

api-server 로그 파일

# 볼륨 경로: volumes/api-server/logs/
tail -200 volumes/api-server/logs/*.log

dashboard-server 로그 파일

# 볼륨 경로: volumes/dashboard-server/logs/
tail -200 volumes/dashboard-server/logs/*.log

---

3. 에이전트 로그

에이전트는 Docker 외부 고객 서버에 설치된다. 원격 접속 후 수집한다.

Java Agent 로그

# 기본 설치 경로
ls -la /opt/flowkat/agent.java/

# 에이전트 로그 (WAS 기동 로그에 포함됨)
# JVM 옵션에 -javaagent:/opt/flowkat/agent.java/flowkat.agent.jar 포함 여부 확인
cat /proc/$(pgrep -f flowkat.agent)/cmdline | tr '\0' '\n' | grep javaagent

Host Agent 로그

# 기본 설치 경로
ls -la /opt/flowkat/agent.host/

# 로그 파일 확인
tail -200 /opt/flowkat/agent.host/logs/*.log

Container Agent 로그 (K8s 환경)

# K8s Pod 내 에이전트 로그
kubectl logs <pod-name> -c flowkat-agent

# 에이전트 conf 확인
kubectl exec <pod-name> -- cat /opt/flowkat/agent.host.container/conf/flowkat.conf

---

4. 헬스체크 스크립트

릴리즈 번들에 포함된 헬스체크 스크립트를 실행하면 진단 결과를 자동으로 수집한다.

Collect Server 헬스체크

# FlowKat 릴리즈 번들 디렉토리에서 실행
./check-collect-server.sh

출력 항목:

• 프로세스 기동 여부
• TCP 6100 포트 리슨 상태
• 에이전트 연결 수
• JVM 힙 사용률

TX-Mining 헬스체크

./check-tx-mining.sh

출력 항목:

• tx-mining-api HTTP 헬스 (/api/v1/health)
• Valkey ping 응답
• PostgreSQL pg_isready 응답
• 파티션 테이블 상태

---

5. 환경 설정 정보 수집

장애 재현 및 원인 분석을 위해 환경 설정을 함께 수집한다.

# .env 파일 (민감 정보 마스킹 후 전달)
grep -v PASSWORD .env | grep -v SECRET > env-masked.txt

# Docker Compose 서비스 목록 및 상태
docker compose ps -a > docker-status.txt

# 서비스 리소스 사용량 (5초 스냅샷)
docker stats --no-stream > docker-stats.txt

# 호스트 디스크 사용량
df -h > disk-usage.txt

# 호스트 메모리 상태
free -h > memory-status.txt

---

6. 벤더 에스컬레이션 패키지 구성

에스컬레이션 시 다음 파일을 압축하여 전달한다.

mkdir escalation-$(date +%Y%m%d-%H%M)
cd escalation-$(date +%Y%m%d-%H%M)

# 1. 서비스 로그 (위 1번 명령 실행 결과)
# 2. 헬스체크 결과
./check-collect-server.sh > check-collect.txt
./check-tx-mining.sh > check-txmining.txt

# 3. 환경 정보
docker compose ps -a > docker-status.txt
docker stats --no-stream > docker-stats.txt
df -h > disk-usage.txt

# 4. 마스킹된 설정 파일
grep -v PASSWORD ../.env | grep -v SECRET > env-masked.txt

# 압축
cd ..
tar czf escalation-$(date +%Y%m%d-%H%M).tar.gz escalation-*/

---

7. 서버 상태 실시간 모니터링

장애 초기 대응 시 로그 수집과 병행하여 서버 리소스 상태를 실시간으로 확인한다. 이상 징후를 조기에 포착하면 에스컬레이션 전에 원인을 좁힐 수 있다.

관련 문서: 14.collect-server.md (Collect 서버 구성), 15.dashboard-server.md (Dashboard 서버 구성)

---

7.1 Docker 컨테이너 리소스 모니터링

모든 컨테이너의 CPU, 메모리, 네트워크, 디스크 I/O를 한 화면에서 실시간으로 확인한다.

# 전체 컨테이너 리소스 사용량 실시간 확인
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"

각 컬럼의 의미는 다음과 같다.

컬럼	의미	이상 징후
Name	컨테이너명	-
CPUPerc	CPU 사용률 (호스트 전체 코어 대비 %)	단일 컨테이너가 지속적으로 80% 초과
MemUsage	현재 메모리 사용량 / 컨테이너 제한	제한의 90% 이상 지속
NetIO	수신 / 송신 누적 바이트	초당 증가량이 평소 대비 10배 이상
BlockIO	디스크 읽기 / 쓰기 누적 바이트	지속적인 쓰기 폭증 (로그 스톰, DB 풀스캔 의심)

--no-stream 옵션을 추가하면 스냅샷 1회만 출력한다. 에스컬레이션 패키지에 포함할 때는 스냅샷으로 수집한다.

# 스냅샷 1회 수집 (에스컬레이션용)
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" > docker-stats-snapshot.txt

---

7.2 JVM 상태 확인 (Collect/API/Dashboard Server)

수집 서버, API 서버, 대시보드 서버 는 JVM 기반 프로세스다. 메모리 누수, GC 과부하, 스레드 증가는 실시간 JVM 지표로 확인한다.

GC 상태 모니터링

# flowkat-collect-server 컨테이너 내 Java 프로세스의 GC 통계 (5초 주기)
docker exec flowkat-collect-server jstat -gcutil $(pgrep java) 5000

출력 컬럼 해석:

컬럼	의미	이상 징후
S0, S1	Survivor 영역 사용률 (%)	지속 100% → Eden 부족
E	Eden 영역 사용률 (%)	지속 100% → Minor GC 과다
O	Old Generation 사용률 (%)	80% 초과 지속 → Major GC 임박
M	Metaspace 사용률 (%)	95% 초과 → 클래스 로딩 이상
YGC	Minor GC 누적 횟수	급격한 증가 → 메모리 압박
YGCT	Minor GC 누적 시간 (초)	-
FGC	Full GC 누적 횟수	증가 중 → 서비스 중단 위험
FGCT	Full GC 누적 시간 (초)	값이 크면 STW 발생
GCT	전체 GC 누적 시간 (초)	가동 시간 대비 10% 초과 시 위험

동일한 명령을 api-server, dashboard-server에도 적용한다.

docker exec flowkat-api-server       jstat -gcutil $(pgrep java) 5000
docker exec flowkat-dashboard-server jstat -gcutil $(pgrep java) 5000

힙 덤프 수집 (OOM 발생 시)

OOM이 의심되거나 Full GC가 반복될 때 힙 덤프를 수집하여 에스컬레이션 패키지에 포함한다.

# flowkat-collect-server 힙 덤프
docker exec flowkat-collect-server \
  jmap -dump:format=b,file=/tmp/heapdump-collect.hprof $(pgrep java)

# 덤프 파일 호스트로 복사
docker cp flowkat-collect-server:/tmp/heapdump-collect.hprof ./heapdump-collect.hprof

스레드 카운트 확인

스레드 수 급증은 에이전트 연결 폭주 또는 데드락 징후다.

# 스레드 수 확인
docker exec flowkat-collect-server \
  sh -c "ps -eLf | grep java | wc -l"

---

7.3 이상 징후 판단 기준

운영 중 다음 기준을 초과하면 즉시 원인을 확인한다.

메트릭	정상 범위	경고	위험	조치
CPU (컨테이너)	0 ~ 50%	50 ~ 80%	80% 초과 지속	처리 중인 요청 수 확인, collect-server 에이전트 연결 수 점검
Memory (JVM Old Gen)	0 ~ 60%	60 ~ 80%	80% 초과 지속	GC 로그 확인, 필요 시 힙 덤프 수집
Full GC 빈도	1회/시간 이하	5분당 1회	1분당 1회 이상	힙 덤프 수집 후 벤더 에스컬레이션
GC Pause (FGCT 증가)	1초/회 이하	1 ~ 3초/회	3초/회 초과	STW로 인한 서비스 지연 가능, 즉시 벤더 보고
Thread Count	100 ~ 300	300 ~ 500	500 초과	에이전트 연결 폭주 또는 데드락 의심, jstack 수집
Network I/O (NetIO)	평상시 기준	평상시 3배	평상시 10배 초과	에이전트 재전송 루프, 로그 스톰 확인

---

7.4 PostgreSQL 모니터링

flowkat-postgres-txmining 컨테이너의 연결 수, 테이블 크기, 슬로우 쿼리를 확인한다.

활성 연결 확인

docker exec flowkat-postgres-txmining \
  psql -U flowkat -c "SELECT * FROM pg_stat_activity WHERE state = 'active';"

주요 확인 항목:

• wait_event_type / wait_event: Lock 이면 잠금 대기 상태
• query_start: 쿼리 시작 시각. 현재 시각과 차이가 크면 장시간 슬로우 쿼리
• query: 실행 중인 SQL 내용

연결 수 요약

-- 상태별 연결 수 집계
SELECT state, count(*) FROM pg_stat_activity GROUP BY state;

docker exec flowkat-postgres-txmining \
  psql -U flowkat -c "SELECT state, count(*) FROM pg_stat_activity GROUP BY state;"

정상 범위: idle 포함 전체 연결 30개 이하. active 상태가 지속적으로 10개 초과하면 tx-mining-api 쪽 처리 지연을 의심한다.

파티션 테이블 크기 확인

tx-mining은 날짜 기반 파티션 테이블을 사용한다. 파티션이 누락되거나 크기가 비정상이면 수집 장애가 발생한다.

-- 파티션 테이블 크기 상위 10개
SELECT
  relname AS table_name,
  pg_size_pretty(pg_total_relation_size(oid)) AS total_size
FROM pg_class
WHERE relkind = 'r'
ORDER BY pg_total_relation_size(oid) DESC
LIMIT 10;

docker exec flowkat-postgres-txmining psql -U flowkat -c "
SELECT relname AS table_name,
       pg_size_pretty(pg_total_relation_size(oid)) AS total_size
FROM pg_class
WHERE relkind = 'r'
ORDER BY pg_total_relation_size(oid) DESC
LIMIT 10;"

---

7.5 Valkey 모니터링

flowkat-valkey 는 tx-mining-api의 캐시 및 세션 저장소다. 메모리 부족이나 명령 처리 지연이 발생하면 tx-mining 전체 응답 속도에 영향을 준다.

메모리 상태 확인

docker exec flowkat-valkey valkey-cli info memory

주요 필드:

필드	의미	이상 징후
used_memory_human	현재 사용 중인 메모리	maxmemory 설정값의 80% 초과
maxmemory_human	최대 메모리 제한	0이면 제한 없음 (OOM 위험)
maxmemory_policy	메모리 초과 시 정책	noeviction 이면 쓰기 오류 발생 가능
mem_fragmentation_ratio	메모리 단편화 비율	1.5 초과 → 단편화 심화, 재시작 검토

통계 및 처리량 확인

docker exec flowkat-valkey valkey-cli info stats

주요 필드:

필드	의미	이상 징후
total_commands_processed	누적 처리 명령 수	-
instantaneous_ops_per_sec	현재 초당 처리 명령 수	평소 대비 급격한 증가
rejected_connections	거부된 연결 수	0 초과 → maxclients 초과
evicted_keys	메모리 부족으로 제거된 키 수	0 초과 → 메모리 부족
keyspace_hits / keyspace_misses	캐시 적중/미적중 수	미적중률 50% 초과 시 캐시 효율 점검

연결된 클라이언트 수 확인

docker exec flowkat-valkey valkey-cli info clients

connected_clients 값이 50 초과이면 tx-mining-api의 연결 풀 설정을 점검한다.

---

관련 문서: *30.troubleshooting-flow.md* (진단 플로우), *layer3-\*.md* (증상별 상세 가이드)