TX-Mining 관련 문의 대응

고객이 트랜잭션 익스플로러(TX-Mining) 관련 문제를 신고할 때의 대응 가이드다. UI 화면 기준 증상 → 기술 원인 → 해결 경로 순으로 진행한다.

용어 규칙: 고객 증상 인용은 UI 라벨(트랜잭션 익스플로러, 트래픽 분석, 검색)을 사용하고, 기술 대응은 시스템 용어(TX-Mining API, flowkat-tx-mining-api)를 사용한다.

---

1. 증상 목록

#	고객이 말하는 증상 (UI 기준)	섹션
S-1	"트랜잭션 익스플로러 화면에 데이터가 안 보입니다"	2.1
S-2	"트랜잭션 익스플로러에서 서버 오류가 납니다"	2.2
S-3	"트랜잭션 익스플로러 조회가 매우 느립니다"	2.3

---

2. 증상별 대응 가이드

2.1 S-1: 데이터가 안 보인다

증상: 트랜잭션 익스플로러 화면(트랜잭션 익스플로러 > 트래픽 분석, 트랜잭션 익스플로러 > 검색 등)에서 조회 기간을 설정하고 검색해도 데이터가 표시되지 않는다.

고객에게 확인

1. 어떤 탭/메뉴인가? (트래픽 분석, 검색, Top N 등)
2. 조회 기간을 어떻게 설정했는가? (최근 1시간, 오늘, 특정 날짜)
3. 에이전트가 정상 연결 상태인가? (센트리 > 에이전트 목록)
4. TX-Mining 서버가 최근에 재시작됐는가?

기술지원 확인

1. TX-Mining API 서버 상태 확인:

docker ps | grep tx-mining
docker logs flowkat-tx-mining-api --tail 50 | grep -i "error\|warn\|start"

2. Health 체크:

curl -s http://localhost:8090/api/v1/health

3. PostgreSQL 파티션 상태 확인:

docker exec flowkat-postgres-txmining psql -U postgres -c \
  "SELECT schemaname, tablename FROM pg_tables WHERE tablename LIKE 'xlog_norm%' ORDER BY tablename DESC LIMIT 5;"

4. Valkey(Redis) 데이터 확인:

docker exec flowkat-valkey redis-cli DBSIZE
# 키가 0이면 캐시 데이터 없음

확인 포인트:

확인 항목	정상 상태	비정상 상태
API Health	{"status":"UP"}	500 또는 Connection refused
파티션 테이블	최근 날짜 파티션 존재	파티션 없음
Valkey 키 수	> 0 (데이터 적재 후)	0 (데이터 없음)
TX-Mining 로그	정상 기동 메시지	에러 반복

벤더 에스컬레이션 시 전달 정보

• TX-Mining API 로그: docker logs flowkat-tx-mining-api (최소 1시간)
• Health API 응답: curl http://localhost:8090/api/v1/health
• DB 파티션 목록 쿼리 결과
• 조회 기간 설정값 (from ~ to 시각)
• 에이전트 연결 상태 (에이전트 수, 연결된 서비스 수)

---

2.2 S-2: API 에러(500/OOM)

증상: 트랜잭션 익스플로러 화면에서 특정 기능 사용 시 화면이 멈추거나 "서버 오류" 메시지가 표시된다. Docker 컨테이너(flowkat-tx-mining-api)가 자동으로 재시작된다.

고객에게 확인

1. 어떤 동작 중 오류가 발생했는가? (특정 탭 클릭, 특정 기간 조회 등)
2. 컨테이너가 자동 재시작된다는 것을 어떻게 알았는가?
3. 조회 기간이 매우 길지 않은가? (30일 이상 등)

기술지원 확인

1. OOM 여부 확인:

docker inspect flowkat-tx-mining-api --format='{{.State.ExitCode}}'
# 137 = OOM Killer, 1 = JVM OOM

docker logs flowkat-tx-mining-api 2>&1 | grep -B5 "OutOfMemoryError"

2. 컨테이너 메모리/JVM 힙 확인:

docker stats flowkat-tx-mining-api --no-stream
docker exec flowkat-tx-mining-api jps -lv | grep -o "\-Xmx[^ ]*"

3. Valkey 메모리 확인:

docker exec flowkat-valkey redis-cli INFO memory | grep used_memory_human
docker exec flowkat-valkey redis-cli DBSIZE

확인 포인트:

확인 항목	정상 상태	비정상 상태
Exit Code	0 (정상 종료)	137 (OOM Killer)
JVM 힙 설정	-Xmx2g 이상	-Xmx512m 등 소용량
Valkey 메모리	적정 수준	급격한 증가
Restart Count	0	증가 중

벤더 에스컬레이션 시 전달 정보

• docker inspect flowkat-tx-mining-api 전체 출력 (State 섹션)
• OOM 발생 직전 API 엔드포인트 (브라우저 Network 탭)
• JVM 힙 설정값 및 컨테이너 메모리 제한값
• docker logs flowkat-tx-mining-api 2>&1 | tail -200 출력
• Valkey 메모리 사용량 및 키 수

---

2.3 S-3: 조회가 느리다

증상: 트랜잭션 익스플로러 조회 시 결과가 나타나는 데 수십 초 이상 소요된다. 또는 API 타임아웃이 발생한다.

고객에게 확인

1. 어떤 조회인가? (트래픽 분석, 검색, 상위 N 등)
2. 조회 기간이 얼마인가? (1시간, 1일, 1주일 등)
3. 현재 서비스/에이전트 수가 얼마나 되는가?

기술지원 확인

1. PostgreSQL 쿼리 실행 시간 확인:

docker exec flowkat-postgres-txmining psql -U postgres -c \
  "SELECT count(*) FROM xlog_norm;"
# 수백만 건 이상이면 파티셔닝 효과 확인 필요

2. 파티션 프루닝 동작 확인:

docker exec flowkat-postgres-txmining psql -U postgres -c \
  "EXPLAIN ANALYZE SELECT count(*) FROM xlog_norm WHERE created_at > NOW() - INTERVAL '1 hour';"
# 파티션 스캔 범위 확인

3. Valkey 키 수 및 TTL 확인:

docker exec flowkat-valkey redis-cli DBSIZE
docker exec flowkat-valkey redis-cli INFO keyspace

확인 포인트:

확인 항목	정상 상태	비정상 상태
xlog_norm 행 수	파티션 별 적정 분산	단일 파티션 수천만 건
EXPLAIN 파티션 스캔	해당 기간 파티션만 스캔	전체 파티션 풀 스캔
Valkey TTL	설정된 만료 시간	TTL 없음(0)

벤더 에스컬레이션 시 전달 정보

• SELECT count(*) FROM xlog_norm 결과
• EXPLAIN ANALYZE 출력 (조회 속도가 느린 쿼리 포함)
• 조회 기간 및 서비스/서버 수
• pg_partman 활성화 여부: SELECT * FROM partman.part_config;
• TX-Mining API 서버 JVM 힙 설정

---

3. 관련 문서

모듈	관련 trouble-shooting	핵심 이슈
OOM 최적화	049-tx-mining-oom-optimization	OOM 원인 API별 패치 확인
파티션 활성화	048-tx-mining-partman-activation	pg_partman 파티셔닝
Valkey 스냅샷	053-tx-mining-valkey-pg-snapshot-fallback	Valkey/PG 폴백
트래픽 분석	062-tx-mining-traffic-analysis-tab	트래픽 분석 탭
이상 감지	070-tx-mining-range-anomaly-detection	범위 이상 감지

---

4. 트러블슈팅 플로우