이클립스 - 톰캣 원격 디버깅 방법 (윈도우, 리눅스)

유지보수를 하다보면 서버(tomcat)에 올라가있는 프로젝트에서 오류를 추적해야될때가 많은데

디버깅을 하지 못한다면 시간과 체력이 낭비될 가능성이 많습니다.

 

저 같은 경우에는 외부 API를 연동하는 테스트 중에 오류가 발생하였는데

이 API가 외부 접속을 허용해야지만 사용가능한 API여서 개방된 포트가 없는 제 로컬 환경에서는

디버깅을 하면서 개발할 수가 없는 상황이었습니다.

 

처음에는 원격 디버깅 기능이 있는지 모르고 오류로 추정되는 위치에

일일이 System.out.println() 함수나 log4j를 사용해서 빌드 배포를 반복하여 버그를 추적했지만

얼마전에 이클립스에서 원격 디버깅 기능을 제공하고 있다는 것을 알았습니다.

사용방법은 다음과 같습니다.

 

1. 원격서버 톰캣 환경 구성

먼저 원격으로 접속할 톰캣의 환경을 설정해야합니다.

윈도우 서버라면 catalina.bat 파일을 수정해야하고 리눅스 서버라면 catalina.sh 파일을 수정해야 합니다.

해당 파일의 위치는 톰캣이 설치된 경로에서 bin폴더로 이동하시면 됩니다.

 

1.1 윈도우 톰캣 환경 구성(catalina.bat)

catalina.bat 파일을 열어 다음과 같이 해당 위치에 명령어를 입력해주시면 됩니다.

(apache-tomcat-8.5.73 버전을 이용해서 테스트를 진행했습니다.)

set "JAVA_OPTS=%JAVA_OPTS% -Xms512m -Xmx1024m -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

 

address 부분에 적혀있는 8000은 톰캣에서 기본으로 세팅되어 있는 JPDA_ADDRESS 입니다.

JPDA는 Java Platform Debugger Architecture의 약자로써

Java 코드를 디버깅하기위한 API 도구 입니다. 톰캣에 기본적으로 내장되어있습니다.

 

1.2 리눅스 톰캣 환경 구성(catalina.sh)

옛날 이미지라 참고만 하시고 -Xdebug 대신 아래의 -agentlib를 사용해주시면 됩니다.

catalina.sh 파일을 열어 다음과 같이 해당 위치에 명령어를 입력해주시면 됩니다. (톰캣 버전별로 조금씩 다릅니다.)

 

apache-tomcat-7.0.103, apache-tomcat-8.5.77

CATALINA_OPTS="-agentlib:jdwp=transport=dt_socket,address=*:8000,server=y,suspend=n"

 

위와 같이 했을때 failed to connect to remote vm. connection refused. connection refused: connect 다음과 같은 오류가 나타나면 address부분을 *: 없이 8000으로만 세팅해보시기 바랍니다.

CATALINA_OPTS="-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n"

 

address 부분에 적혀있는 8000은 톰캣에서 기본으로 세팅되어 있는 JPDA_ADDRESS 입니다.

JPDA는 Java Platform Debugger Architecture의 약자로써

Java 코드를 디버깅하기위한 API 도구 입니다. 톰캣에 기본적으로 내장되어있습니다.

(포트번호는 바꾸어도 되지만 기본적으로 개방되어 있어야 합니다~!)

 

2. 이클립스 환경 구성

화면 상단 메뉴에서 [RUN] > [Debug Configurations...] > [Remote Java Application]을 선택한 뒤 오른쪽 마우스 클릭하여 [New Configuration]을 선택하면 다음과 같은 화면이 나옵니다. 아래의 빈칸들을 하나씩 채워주시면 됩니다.

Name : 디버깅 이름(또는 프로젝트 이름)
Project : Java Project
Host : 원격 IP 주소
Port : 8000(또는 catalina 파일에서 설정한 JPDA 포트)

 

Project는  [RUN] > [Debug Configurations...] > [Source] 탭에서 다시 불러올 수 있으므로

원격 서버랑 WAR 파일이나 프로젝트가 다르더라도 디버깅 자체는 실행되니 우선 원격 디버깅이 붙는지 부터 확인하는것이 좋습니다.

설정 완료 후 [Apply] 버튼과 [Debug] 버튼을 차례로 클릭합니다.

 

3. 원격 연결이 안된 경우 확인해야되는것

위의 방법대로 했는데 connection refused 또는 connection timeout이 발생하는 경우에는

다음 주의사항을 한번 확인해보시기 바랍니다.

 

1. 외부에서 접근가능한 포트인지??

address에서 사용하는 포트가 외부에서 접근가능한 포트인지 확인해야합니다.
ipconfig에서 나오는 IPv4주소와 포트번호로 다른 외부 PC에서 접속이 가능한지 확인해보세요~!

 

1. JAVA_OPTS, CATALINA_OPTS, JPDA_OPTS 중에 어떤걸 써야하나??

window 톰캣 8.6 버전 사용시에는 JAVA_OPTS를 사용했는데
linux 톰캣 7 버전 사용시에는 JAVA_OPTS와 JDPA_OPTS로 연결이 안되서 CATALINA_OPTS를 사용했습니다.

 

2. -agentlib:jdwp 와 -Xdebug -Xrunjdwp 중에 어떤걸 써야하나?

Java 5.0 이상 사용시 -agentlib:jdwp 사용하시면 됩니다.
-Xdebug -Xrunjdwp 도 오류는 나지 않지만 더이상 사용되지 않는 옵션이며 속도가 더 느리다고 합니다.

[참고] https://stackoverflow.com/questions/138511/what-are-java-command-line-options-to-set-to-allow-jvm-to-be-remotely-debugged

 

3. address

많은 블로그에서 address에 포트만 넣어서 사용하는데 그런 경우에는 로컬 톰캣에서 테스트해서 가능했던것이고
기본적으로는 JPDA_ADDRESS가 localhost:8000으로 되어있기 때문에 전체 IP주소를 입력해야 합니다.
(catalina.sh 또는 catalina.bat 파일에서 조금 내리다 보면 JPDA_ADDRESS가 localhost:8000으로 되어있는 것을 볼 수 있습니다.)

ex) IP주소 : 8000 또는 *:8000
[참고] https://stackovergo.com/ko/q/877295/remote-debugging-tomcat-with-eclipse

 

4. Source not found

디버깅은 성공했는데 이클립스에서 프로젝트에 접속할 수 없다면
[RUN] > [Debug Configurations...] > [Source]탭으로 이동해 디프로젝트를 다시 [Add]하면 됩니다.

[참고] https://skillazit.tistory.com/13