시스템 관리_23 톰캣 WAS 애플리케이션 재배포 시 발생하는 java.lang.OutOfMemoryError Metaspace 오류 원인 분석 및 해결 가이드

# 1. 톰캣 catalina.out 로그에서 Metaspace OOM 및 클래스로더 경고 확인
$ tail -n 50 /opt/tomcat/logs/catalina.out
# [출력 예시]
# java.lang.OutOfMemoryError: Metaspace
# WARNING [http-nio-8080-exec-5] org.apache.catalina.loader.WebappClassLoaderBase.clearReferencesJdbc 
# The web application [ROOT] registered the JDBC driver [com.mysql.cj.jdbc.Driver] but failed to unregister it when the web application was stopped. 
# To prevent a memory leak, the JDBC Driver has been forcibly unregistered.
# WARNING [http-nio-8080-exec-5] org.apache.catalina.loader.WebappClassLoaderBase.clearReferencesThreads 
# The web application [ROOT] appears to have started a thread named [abandoned-connection-cleanup] but has failed to stop it.

# 2. 톰캣 PID 확인 및 JVM Metaspace 관련 구동 인자 확인
$ ps -ef | grep -E 'tomcat|Bootstrap' | grep -v grep
# -> -XX:MetaspaceSize 및 -XX:MaxMetaspaceSize 설정 여부 확인

# 3. 실시간 Metaspace 사용량 및 클래스 로딩 수치 모니터링 (jstat)
# MC: Metaspace Capacity(KB), MU: Metaspace Utilization(KB), CCSC: Compressed Class Capacity, CCSU: Compressed Class Utilization
$ jstat -gc 32145 1000 3
# 또는 퍼센트 단위 확인 (-gcutil)
$ jstat -gcutil 32145 1000 3
  S0     S1     E      O      M     CCS    YGC     YGCT    FGC    FGCT     CGC    CGCT     GCT   
  0.00   0.00  42.50  31.20  99.85  98.12     12    0.210     5    1.420     -       -     1.630
# -> 재배포 후 M(Metaspace) 점유율이 낮아지지 않고 99% 이상으로 유지되는지 확인

# 4. JVM에 로드된 클래스 수 및 로더 인스턴스 확인 (jcmd)
$ sudo -u tomcat jcmd 32145 VM.classloader_stats
# [출력 예시]
# Loader Class                                 Parent Class                                  Loaded Classes
# org.apache.catalina.loader.ParallelWebappClassLoader ... 4520
# org.apache.catalina.loader.ParallelWebappClassLoader ... 4518  <-- 이전 배포 버전의 클래스로더가 언로드되지 않고 남아있음!

#!/bin/bash
# check_metaspace_leak.sh - Diagnose Tomcat Metaspace usage and ClassLoader leaks

echo "=========================================="
echo " [톰캣 Metaspace 및 클래스로더 누수 진단]"
echo "=========================================="

# 1. 톰캣 프로세스 감지
TOMCAT_PID=$(pgrep -f "org.apache.catalina.startup.Bootstrap" | head -n 1)

if [ -z "$TOMCAT_PID" ]; then
    echo "  [오류] 구동 중인 톰캣 프로세스를 찾을 수 없습니다."
    exit 1
fi

TOMCAT_USER=$(ps -o user= -p "$TOMCAT_PID")
echo "  - 톰캣 PID  : ${TOMCAT_PID}"
echo "  - 실행 계정 : ${TOMCAT_USER}"

# 2. Metaspace 옵션 확인
JVM_ARGS=$(ps -p "$TOMCAT_PID" -o args=)
MAX_META=$(echo "$JVM_ARGS" | grep -oE "\-XX:MaxMetaspaceSize=[0-9]+[kmgKMG]")
INIT_META=$(echo "$JVM_ARGS" | grep -oE "\-XX:MetaspaceSize=[0-9]+[kmgKMG]")

echo -e "\n[1] JVM Metaspace 메모리 한도 설정:"
echo "  - 초기 크기(-XX:MetaspaceSize)    : ${INIT_META:-"미설정 (기본값 사용)"}"
echo "  - 최대 크기(-XX:MaxMetaspaceSize) : ${MAX_META:-"무제한 (시스템 가용 물리 메모리 전체 소비 가능)"}"

# 3. 실시간 Metaspace 소비량 및 로드된 클래스 수
echo -e "\n[2] 클래스 로딩 및 Metaspace 사용량 통계:"
if command -v jstat &>/dev/null; then
    CLASS_STATS=$(sudo -u "$TOMCAT_USER" jstat -class "$TOMCAT_PID" | tail -n 1)
    LOADED_CLASSES=$(echo "$CLASS_STATS" | awk '{print $1}')
    UNLOADED_CLASSES=$(echo "$CLASS_STATS" | awk '{print $3}')
    
    META_STATS=$(sudo -u "$TOMCAT_USER" jstat -gcutil "$TOMCAT_PID" | tail -n 1)
    META_PERCENT=$(echo "$META_STATS" | awk '{print $5}')

    echo "  - 현재 로드된 클래스 수   : ${LOADED_CLASSES}개"
    echo "  - 언로드(회수)된 클래스 수 : ${UNLOADED_CLASSES}개"
    echo "  - Metaspace 점유율        : ${META_PERCENT}%"
else
    echo "  [안내] jstat 명령어를 사용할 수 없습니다."
fi

# 4. WebappClassLoader 누수 검사 (jcmd)
echo -e "\n[3] WebappClassLoader 인스턴스 잔존 여부 검증:"
if command -v jcmd &>/dev/null; then
    LOADER_DUMP=$(sudo -u "$TOMCAT_USER" jcmd "$TOMCAT_PID" VM.classloader_stats 2>/dev/null)
    WEBAPP_LOADERS=$(echo "$LOADER_DUMP" | grep -c "ParallelWebappClassLoader\|WebappClassLoader")

    echo "  - 감지된 활성 WebappClassLoader 수: ${WEBAPP_LOADERS}개"
    if [ "$WEBAPP_LOADERS" -gt 1 ]; then
        echo "  [위험] 이전 배포본의 ClassLoader가 GC되지 않고 메모리에 남아있습니다!"
        echo "  -> 애플리케이션 재배포(Redeploy) 누수로 인한 Metaspace OOM 발생 위험 매우 높음."
    else
        echo "  [정상] 단일 WebappClassLoader만 활성화되어 있습니다."
    fi
else
    echo "  [안내] jcmd 명령어를 사용할 수 없습니다."
fi

echo -e "\n=========================================="
echo " [진단 완료]"
echo "=========================================="

# /opt/tomcat/bin/setenv.sh
export CATALINA_OPTS="$CATALINA_OPTS \
-XX:MetaspaceSize=256m \
-XX:MaxMetaspaceSize=512m"