본문으로 건너뛰기

운영 FAQ

일상 운영 중 자주 발생하는 문제와 해결 방법입니다.

빠른 자가진단
🩺자가진단시작

어떤 문제가 있나요?

대시보드​

대시보드에 데이터가 표시되지 않습니다​

에이전트 연결 상태 확인, Collect 서버 로그 확인, DB 시퀀스 불일치 검사를 통해 원인을 파악합니다. 에이전트 미연결 또는 DB 시퀀스 오류가 주된 원인입니다.

대시보드 편집 모드에서 저장이 되지 않습니다​

Docker 로그에서 23505 에러 및 시퀀스 불일치를 확인한 후 Dashboard 서버를 재시작하면 H2 시퀀스가 자동으로 복구됩니다.

대시보드 위젯의 배치가 저장 후 다르게 표시됩니다​

GridLayout 관련 오류 여부를 서버 로그에서 확인하고, 브라우저 DevTools의 Local Storage와 콘솔을 점검하여 레이아웃 상태를 검증합니다.

권한/인증​

로그인 후 계속 로그인 화면으로 돌아갑니다​

nginx 에러 로그에서 세션 헤더 초과(too big header) 여부를 확인하고, proxy_buffer_size를 16k로 설정하여 해결합니다.

로그인했는데 갑자기 로그아웃됩니다​

Dashboard 서버 로그에서 세션 토큰 만료 주기를 확인하고, WebSocket 연결 상태(STOMP)를 검증하여 세션 관리 이상을 파악합니다.

502 Bad Gateway 오류가 발생합니다​

nginx 에러 로그에서 "upstream sent too big header" 여부를 확인하고, proxy_buffer_size 설정을 확인하여 적용하거나 컨테이너를 재시작합니다.

특정 메뉴가 보이지 않거나 접근이 거부됩니다​

역할 관리 화면에서 해당 메뉴의 기능 권한 부여 여부를 확인하고, 역할 API와 Zustand 상태를 검증합니다.

관리자가 권한을 변경했는데 즉시 반영되지 않습니다​

WebSocket 연결 상태를 DevTools에서 확인하고, nginx WebSocket 프록시 설정(/upgrade)을 검증하여 STOMP 구독을 재설정합니다.

역할 생성 또는 수정 시 오류가 발생합니다​

역할 관리 API 로그를 확인하고, 브라우저 Network 탭에서 실패한 요청의 응답 코드와 본문을 검증합니다.

트랜잭션 익스플로러​

트랜잭션 익스플로러 화면에 데이터가 표시되지 않습니다​

트랜잭션 익스플로러 API 서버 상태 확인, Health 체크, PostgreSQL 파티션 상태 검증, Valkey 데이터 확인을 통해 데이터 적재 문제를 파악합니다.

트랜잭션 익스플로러에서 500 오류 또는 OOM 발생합니다​

컨테이너 Exit Code 137(OOM) 여부 확인, JVM 힙 설정 검증, Valkey 메모리 상태 점검으로 메모리 부족을 해결합니다.

트랜잭션 익스플로러 조회가 매우 느립니다​

xlog_norm 행 수 파티션 분산 확인, EXPLAIN ANALYZE로 쿼리 계획 검증, Valkey TTL 설정 확인으로 조회 성능을 개선합니다.

XLog에서 SQL 프로파일 정보가 나오지 않습니다​

에이전트 로그에서 JDBC 클래스 후킹 여부 확인, flowkat.conf의 profile_sql_escape_enabled 파라미터 검증, Connection Pool 래퍼 클래스 패턴(hook_jdbc_wrapping_driver_patterns) 설정을 확인합니다.

XLog에서 Connection 관련 프로파일 정보가 수집되지 않습니다​

profile_connection_open_enabled 파라미터 확인, 커스텀 DataSource 클래스에 대한 추가 패턴 설정(hook_get_connection_patterns), 에이전트 재기동을 통해 해결합니다.

대시보드에 JDBC Connection 수가 표시되지 않습니다​

jmx_counter_enabled 파라미터 활성화, HikariCP의 register-mbeans=true 설정 확인, JMX MBean 조회를 통해 Connection 카운터를 활성화합니다.

특정 ORM/프레임워크에서 SQL이 수집되지 않습니다​

hook_jdbc_wrapping_driver_patterns에 해당 Connection Pool 래퍼 클래스 등록, 에이전트 재기동, ORM별 추가 패턴 설정(hook_jdbc_pstmt_classes 등)을 통해 SQL 수집을 활성화합니다.

알림​

알람이 발생했는데 외부 알림을 받지 못했습니다​

알람 이력 API 조회로 알람 기록 확인, 알람 규칙 활성 상태 검증, 알림 채널(이메일/Webhook) 설정 및 연결 검사를 수행합니다.

같은 알람이 너무 많이 반복 발생합니다​

알람 규칙의 쿨다운(억제) 설정 확인, 임계값이 과도하게 낮은 설정 여부 검증, 알람 발생 빈도를 모니터링하여 규칙을 조정합니다.

알람 설정/조회 시 API 오류가 발생합니다​

API URL 형식 검증(/meerkat prefix 확인), 날짜 파라미터 형식(YYYYMMDD) 확인, API 서버 상태 및 컨테이너 로그를 검증합니다.

추가 참조