JDBC 모니터링 문제 대응
고객이 JDBC/SQL 모니터링 관련 문제를 신고할 때의 대응 가이드다. UI 화면 기준 증상 → 기술 원인 → 해결 경로 순으로 진행한다.
1. 증상 목록
| # | 고객이 말하는 증상 (UI 기준) | 섹션 |
|---|---|---|
| S-1 | "XLog에서 SQL 프로파일 정보가 나오지 않는다" | 2.1 |
| S-2 | "XLog에서 Connection 관련 프로파일 정보가 수집되지 않는다" | 2.2 |
| S-3 | "대시보드에 JDBC Connection 수가 표시되지 않는다" | 2.3 |
| S-4 | "특정 ORM/프레임워크에서 SQL이 수집되지 않는다" | 2.4 |
2. 증상별 대응 가이드
2.1 S-1: SQL 프로파일 정보가 나오지 않는다
증상: XLog 상세 화면에서 SQL 항목이 비어 있거나, Active Service 화면에서 현재 실행 중인 SQL이 보이지 않는다.
JDBC BCI 후킹 구조 이해
FlowKat Java 에이전트는 BCI(Byte Code Instrumentation)를 사용하여 JDBC 클래스를 후킹한다. 에이전트가 JVM 기동 시 JDBC 드라이버 클래스를 감지하고, PreparedStatement, Statement, ResultSet 메서드에 프로파일 수집 로직을 삽입한다.
후킹이 실패하는 주요 원인은 두 가지다:
- direct_sql 모드: JDBC 드라이버가 표준
java.sql.*인터페이스를 직접 구현하는 경우 — 에이전트가 자동으로 후킹 가능하다. - wrapping 모드: JDBC 드라이버가 별도 래퍼 클래스를 통해 실행되는 경우 (HikariCP, DBCP2 등 Connection Pool의 래퍼 클래스) —
hook_jdbc_wrapping_driver_patterns설정이 필요하다.
고객에게 확인
- 어떤 데이터베이스를 사용하는가? (Oracle, MySQL, PostgreSQL, MSSQL 등)
- Connection Pool을 사용하는가? (HikariCP, DBCP2, c3p0, Tomcat JDBC 등)
- ORM 또는 SQL 매퍼를 사용하는가? (MyBatis, Hibernate, JPA 등)
- SQL이 전혀 수집되지 않는가, 아니면 특정 쿼리만 수집되지 않는가?
- XLog 상세 화면(
트랜잭션 익스플로러 > XLog > 상세)에서 SQL 탭이 비어 있는가?
확인 경로: 트랜잭션 익스플로러 > XLog > 상세 팝업
확인 항목: SQL 프로파일 탭 — 쿼리 텍스트, 실행 시간, 파라미터 표시 여부
기술지원 확인
- 에이전트 로그에서 JDBC 클래스 후킹 여부 확인:
# 에이전트 기동 로그에서 JDBC 후킹 감지 확인
grep -i "jdbc\|hooking\|instrument\|datasource" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log | head -30
profile_sql_escape_enabled및 SQL 수집 관련 파라미터 확인:
# flowkat.conf에서 JDBC 관련 파라미터 확인
grep -E "profile_sql|hook_jdbc|profile_connection|xlog_error_sql" $FLOWKAT_HOME/conf/flowkat.conf
- 현재 적용된 파라미터 기본값 확인:
| 파라미터 | 기본값 | conf 키 | 설명 |
|---|---|---|---|
profile_sql_escape_enabled | true | profile_sql_escape_enabled | SQL 리터럴 파라미터 정규화 (바인드 파라미터 치환) |
profile_sqlmap_name_enabled | true | profile_sqlmap_name_enabled | MyBatis SQL Map ID 수집 여부 |
profile_connection_open_enabled | true | profile_connection_open_enabled | DB Connection 오픈 프로파일 수집 여부 |
xlog_error_sql_time_max_ms | 30000 | xlog_error_sql_time_max_ms | 이 시간 초과 시 XLog에 SQL 오류 마킹 (ms) |
xlog_error_jdbc_fetch_max | 10000 | xlog_error_jdbc_fetch_max | 이 건수 초과 fetch 시 XLog에 오류 마킹 |
- wrapping 드라이버 패턴 설정이 필요한지 확인:
# Connection Pool 클래스 확인 (HikariCP 사용 예)
grep -i "hikari\|dbcp\|c3p0\|tomcat.jdbc" $APP_HOME/lib/*.jar 2>/dev/null
# 또는
find $APP_HOME -name "*.jar" | xargs -I{} jar -tf {} 2>/dev/null | grep -i "HikariDataSource\|BasicDataSource"
hook_jdbc_wrapping_driver_patterns적용이 필요한 경우:
# $FLOWKAT_HOME/conf/flowkat.conf
# HikariCP 사용 시
hook_jdbc_wrapping_driver_patterns=com.zaxxer.hikari.pool.HikariProxyConnection
# Apache DBCP2 사용 시
hook_jdbc_wrapping_driver_patterns=org.apache.commons.dbcp2.DelegatingConnection
# 복수 설정 (쉼표로 구분)
hook_jdbc_wrapping_driver_patterns=com.zaxxer.hikari.pool.HikariProxyConnection,org.apache.commons.dbcp2.DelegatingConnection
주의: hook_jdbc_wrapping_driver_patterns 변경 후 에이전트 재기동이 필요하다. BCI는 JVM 기동 시에만 적용되기 때문이다.
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| 에이전트 기동 로그 | JDBC 클래스 후킹 감지 메시지 | 후킹 메시지 없음 |
| XLog SQL 탭 | 쿼리 텍스트 및 실행 시간 표시 | 비어 있음 |
profile_sql_escape_enabled | true (기본값) | false로 잘못 설정 |
| wrapping 드라이버 | 패턴이 실제 CP 클래스와 일치 | 패턴 불일치 또는 미설정 |
벤더 에스컬레이션 시 전달 정보
- 에이전트 기동 로그 전체 (
$FLOWKAT_HOME/logs/기동 시점 로그) -
$FLOWKAT_HOME/conf/flowkat.conf전체 내용 - 사용 중인 JDBC 드라이버 JAR 파일명 및 버전 (
ls $APP_HOME/WEB-INF/lib/*.jar | grep -i driver) - 사용 중인 Connection Pool 라이브러리 및 버전
- ORM/SQL 매퍼 종류 및 버전 (MyBatis, Hibernate 등)
- JVM 버전:
java -version - 에이전트 버전:
cat $FLOWKAT_HOME/VERSION - SQL이 수집되지 않는 특정 쿼리 예시 (민감 정보 제거 후)
2.2 S-2: Connection 관련 프로파일 정보가 수집되지 않는다
증상: XLog 상세 화면에서 SQL은 보이지만, DB Connection 획득(open) 시간이 표시되지 않는다. 또는 Connection 획득 지연이 발생하는데 XLog에서 원인을 파악할 수 없다.
고객에게 확인
- XLog 상세 화면에서 SQL 항목은 보이는가?
- SQL 앞에 Connection 획득 항목(DB Connection open)이 보이지 않는가?
- Connection Pool 대기 시간이 길다는 증상이 있는가?
profile_connection_open_enabled파라미터를 명시적으로false로 설정한 적이 있는가?
확인 경로: 트랜잭션 익스플로러 > XLog > 상세 팝업 > SQL 프로파일 탭
확인 항목: SQL 항목 앞에 "DB Connection open" 프로파일 라인 존재 여부
기술지원 확인
- Connection 프로파일 수집 파라미터 확인:
grep -E "profile_connection|hook_connection|hook_get_connection|_profile_fullstack_sql_connection" $FLOWKAT_HOME/conf/flowkat.conf
- 관련 파라미터 현황:
| 파라미터 | 기본값 | conf 키 | 설명 |
|---|---|---|---|
profile_connection_open_enabled | true | profile_connection_open_enabled | DB Connection 오픈 프로파일 수집 |
profile_connection_open_fullstack_enabled | false | profile_connection_open_fullstack_enabled | Connection 오픈 시 Stack Trace 수집 (성능 영향 있음) |
profile_connection_autocommit_status_enabled | false | profile_connection_autocommit_status_enabled | AutoCommit 상태 변경 프로파일 수집 |
hook_connection_open_patterns | "" | hook_connection_open_patterns | 추가 Connection 오픈 메서드 후킹 패턴 |
hook_get_connection_patterns | "" | hook_get_connection_patterns | 추가 getConnection 메서드 후킹 패턴 |
_profile_fullstack_sql_connection_enabled | false | _profile_fullstack_sql_connection_enabled | SQL 실행 시 Connection 관련 전체 스택 수집 (고급) |
- Connection Pool이 FlowKat 표준 후킹 범위를 벗어난 경우 추가 패턴 설정:
# $FLOWKAT_HOME/conf/flowkat.conf
# 커스텀 DataSource의 getConnection 메서드 후킹 추가
hook_get_connection_patterns=com.myapp.datasource.CustomDataSource.getConnection
- 에이전트 로그에서 Connection 후킹 감지 확인:
grep -i "connection\|datasource\|lookup" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log | head -20
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
profile_connection_open_enabled | true | false (비활성화됨) |
| XLog Connection 프로파일 | SQL 항목 앞에 "DB Connection open" 표시 | SQL만 표시, Connection 항목 없음 |
| DataSource 클래스 | FlowKat 표준 후킹 대상 | 커스텀 래퍼 클래스로 후킹 불가 |
벤더 에스컬레이션 시 전달 정보
-
$FLOWKAT_HOME/conf/flowkat.conf(profile_connection_*,hook_connection_*관련 설정) - 에이전트 기동 로그 (JDBC/DataSource 후킹 감지 부분)
- DataSource 설정 파일 (Spring applicationContext.xml, application.yml 등의 DataSource 빈 정의 — 민감 정보 제거 후)
- Connection Pool 클래스명 및 버전
- Connection 오픈 지연이 발생하는 경우 해당 시간대 XLog 화면 캡처
2.3 S-3: JDBC Connection 수가 표시되지 않는다
증상: FlowKat 대시보드 또는 ActiveObject 화면에서 JDBC Connection 카운터(Active Connections, Pool Size 등)가 0으로 표시되거나 항목 자체가 없다.
고객에게 확인
- 대시보드의 어떤 위젯에서 Connection 수를 확인하려 하는가?
- 현재 애플리케이션에서 DB 연결이 정상적으로 동작하는가? (SQL은 정상 수집되는가?)
- Connection Pool 설정에서 JMX 또는 메트릭 노출을 비활성화한 적이 있는가?
확인 경로: 대시보드 > JDBC Connection 위젯 또는 Active Services 화면
확인 항목: Active DB Connections 수치
기술지원 확인
- JMX 카운터 활성화 여부 확인:
grep -E "jmx_counter_enabled|summary_enabled" $FLOWKAT_HOME/conf/flowkat.conf
- JMX 관련 파라미터:
| 파라미터 | 기본값 | conf 키 | 설명 |
|---|---|---|---|
jmx_counter_enabled | false | jmx_counter_enabled | JMX 카운터 수집 활성화 |
summary_enabled | true | summary_enabled | 서비스 요약 정보 수집 활성화 |
__control_connection_leak_autoclose_enabled | false | __control_connection_leak_autoclose_enabled | Connection Leak 자동 닫기 (실험적) |
- Connection 카운터가 수집되려면 JMX를 통한 Connection Pool 정보 노출이 필요하다. HikariCP의 경우
registerMbeans=true설정이 필요하다:
# HikariCP 설정 예 (application.properties)
spring.datasource.hikari.register-mbeans=true
- 에이전트 로그에서 JMX 수집 확인:
grep -i "jmx\|mbeans\|mbean" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log | head -20
- Connection Leak 탐지 기능 확인:
# Connection Leak 탐지 로그
grep -i "connection leak\|_summary_connection_leak" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
jmx_counter_enabled | true (JMX 카운터 사용 시) | false (기본값, JMX 미수집) |
| HikariCP JMX | register-mbeans=true | register-mbeans=false 또는 미설정 |
| 대시보드 Connection 위젯 | 실시간 Connection 수 표시 | 0 또는 항목 없음 |
벤더 에스컬레이션 시 전달 정보
-
$FLOWKAT_HOME/conf/flowkat.conf전체 - Connection Pool 설정 파일 (spring 설정, hikari.properties 등 — 민감 정보 제거 후)
- Connection Pool 종류 및 버전
- JMX 활성화 여부 확인 결과 (
jconsole또는jmxterm으로 MBean 조회 결과) - 에이전트 버전 및 JVM 버전
2.4 S-4: 특정 ORM/프레임워크에서 SQL이 수집되지 않는다
증상: 표준 JDBC는 정상 수집되지만, MyBatis, Hibernate, JPA, Spring Data JPA, QueryDSL 등 특정 ORM/SQL 매퍼 사용 시 SQL이 수집되지 않거나 SQL 텍스트가 비어 있다.
ORM별 수집 특성 이해
FlowKat Java 에이전트의 JDBC 후킹은 최종적으로 java.sql.PreparedStatement.execute*() 또는 java.sql.Statement.execute*() 호출을 포착한다. ORM/프레임워크가 이 경로를 통하면 자동 수집된다.
수집이 안 되는 경우는 다음 원인 중 하나다:
- ORM이 내부 래퍼 클래스를 사용하여 표준 JDBC 인터페이스를 우회한다.
hook_jdbc_wrapping_driver_patterns에 해당 래퍼 클래스가 등록되지 않았다.- Spring Data JPA + Hibernate의 경우, Hibernate의 내부 최적화로 실제 JDBC 호출 경로가 다를 수 있다.
고객에게 확인
- 어떤 ORM 또는 SQL 매퍼를 사용하는가?
- 해당 ORM 외에 직접 JDBC로 실행하는 쿼리는 수집되는가?
- MyBatis를 사용하는 경우, SQL Map ID가 XLog에 표시되는가?
- 수집되지 않는 SQL이 특정 쿼리 유형인가? (SELECT, INSERT, 프로시저 등)
확인 경로: 트랜잭션 익스플로러 > XLog > 상세 팝업 > SQL 탭
확인 항목: SQL Map ID 표시 여부 (MyBatis), SQL 텍스트 내용
기술지원 확인
- MyBatis SQL Map ID 수집 파라미터 확인:
grep -E "profile_sqlmap_name_enabled" $FLOWKAT_HOME/conf/flowkat.conf
- ORM 종류별
hook_jdbc_wrapping_driver_patterns설정 가이드:
# $FLOWKAT_HOME/conf/flowkat.conf
# MyBatis + HikariCP 조합 예
hook_jdbc_wrapping_driver_patterns=com.zaxxer.hikari.pool.HikariProxyConnection
# Hibernate + DBCP2 조합 예
hook_jdbc_wrapping_driver_patterns=org.apache.commons.dbcp2.DelegatingConnection
# Spring Data JPA + HikariCP (일반적)
hook_jdbc_wrapping_driver_patterns=com.zaxxer.hikari.pool.HikariProxyConnection
# QueryDSL은 최종적으로 JPA/JDBC를 통하므로 일반 HikariCP 패턴으로 해결되는 경우가 많음
- Oracle Stored Procedure(CallStatement) 추적 파라미터:
grep "hook_jdbc_oracle_cstat_capture_enabled" $FLOWKAT_HOME/conf/flowkat.conf
| 파라미터 | 기본값 | conf 키 | 설명 |
|---|---|---|---|
profile_sqlmap_name_enabled | true | profile_sqlmap_name_enabled | MyBatis SQL Map ID를 XLog에 표시 |
hook_jdbc_pstmt_classes | "" | hook_jdbc_pstmt_classes | 추가 PreparedStatement 클래스 후킹 패턴 |
hook_jdbc_stmt_classes | "" | hook_jdbc_stmt_classes | 추가 Statement 클래스 후킹 패턴 |
hook_jdbc_rs_classes | "" | hook_jdbc_rs_classes | 추가 ResultSet 클래스 후킹 패턴 |
hook_jdbc_wrapping_driver_patterns | "" | hook_jdbc_wrapping_driver_patterns | DB Connection 래퍼 클래스 패턴 |
hook_jdbc_oracle_cstat_capture_enabled | true | hook_jdbc_oracle_cstat_capture_enabled | Oracle CallStatement 파라미터 캡처 |
- 래퍼 클래스 패턴 변경 후 에이전트 재기동 필수:
# 에이전트 재기동 후 후킹 적용 확인
grep -i "jdbc.*hook\|wrapping\|pstmt\|stmt hook" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log | head -20
- Hibernate native SQL 사용 시 직접 후킹 패턴 추가가 필요할 수 있다:
# $FLOWKAT_HOME/conf/flowkat.conf
# Hibernate 내부 PreparedStatement 래퍼 후킹 (버전에 따라 다름)
hook_jdbc_pstmt_classes=org.hibernate.engine.jdbc.internal.StatementPreparerImpl
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| MyBatis SQL Map ID | XLog SQL 탭에 Mapper ID 표시 | SQL 텍스트만 있고 ID 없음 |
| ORM 래퍼 클래스 | hook_jdbc_wrapping_driver_patterns에 등록됨 | 미등록 → SQL 수집 불가 |
| 에이전트 재기동 | 패턴 변경 후 재기동 완료 | 재기동 없이 패턴만 변경 (미적용) |
| Oracle SP 파라미터 | CallStatement 파라미터 캡처됨 | hook_jdbc_oracle_cstat_capture_enabled=false |
벤더 에스컬레이션 시 전달 정보
- ORM/SQL 매퍼 종류 및 버전 (예: MyBatis 3.5.x, Hibernate 5.6.x)
- JDBC 드라이버 JAR 파일명 및 버전
- Connection Pool 클래스명 및 버전
-
$FLOWKAT_HOME/conf/flowkat.conf(hook_jdbc_*,profile_sql*관련 설정 전체) - 에이전트 기동 직후 로그 (BCI 후킹 적용 결과)
- 수집되지 않는 SQL 예시 코드 (Java 코드 레벨 — MyBatis Mapper 인터페이스, Repository 메서드 등)
- 에이전트 버전:
cat $FLOWKAT_HOME/VERSION - JVM 버전:
java -version
3. 관련 파라미터 요약
JDBC 모니터링 관련 주요 파라미터의 전체 목록이다. 상세 파라미터 설명은 파라미터 기본편을 참조한다.
| 파라미터 | 기본값 | 관련 증상 |
|---|---|---|
profile_sql_escape_enabled | true | S-1: SQL 파라미터 정규화 |
profile_sqlmap_name_enabled | true | S-4: MyBatis SQL Map ID 수집 |
profile_connection_open_enabled | true | S-2: Connection 오픈 프로파일 |
profile_connection_open_fullstack_enabled | false | S-2: Connection 오픈 Stack Trace |
profile_connection_autocommit_status_enabled | false | S-2: AutoCommit 상태 프로파일 |
xlog_error_sql_time_max_ms | 30000 | S-1: 느린 SQL 오류 마킹 기준 |
xlog_error_jdbc_fetch_max | 10000 | S-1: 과다 fetch 오류 마킹 기준 |
hook_jdbc_wrapping_driver_patterns | "" | S-1, S-4: CP 래퍼 클래스 후킹 |
hook_jdbc_pstmt_classes | "" | S-4: 추가 PreparedStatement 후킹 |
hook_jdbc_stmt_classes | "" | S-4: 추가 Statement 후킹 |
hook_jdbc_rs_classes | "" | S-4: 추가 ResultSet 후킹 |
hook_jdbc_oracle_cstat_capture_enabled | true | S-4: Oracle SP 파라미터 캡처 |
jmx_counter_enabled | false | S-3: JMX Connection 카운터 |
hook_connection_open_patterns | "" | S-2: 추가 Connection 오픈 후킹 |
hook_get_connection_patterns | "" | S-2: 추가 getConnection 후킹 |
4. 관련 문서
| 문서 | 링크 | 참조 목적 |
|---|---|---|
| Java 에이전트 설치/설정 | 10.agent-java.md | 에이전트 설치 및 기본 설정 |
| Java 에이전트 파라미터 | 10-1.agent-java-params.md | hook_jdbc_*, profile_* 파라미터 전체 목록 |
| 에이전트 연결 문의 | 23.support-agent-connection.md | 에이전트 연결 불가 시 대응 |