How to attach a Debugger to a running Tomcat or Glassfish instance

This is a frequently asked question from many of our customers at Virtual Pair Programmers, so I thought a blog post to capture the details would be in order. I’ll focus on Tomcat and Glassfish here, because we use them on our courses – but the details are the same for other servers.

• (for Glassfish) 1) Run the server under debug. The easiest way is to run as normal, then go to the admin console. Go to configurations -> server-config (not default config) -> JVM Settings. Click Debug Enabled. These options will be different on different glassfish versions (I’m on 4), but you should be able to find them. Check the port that the debugger will run on – it will be part of the debug options and usually the default is 9009

  (for Tomcat) 1) Add a JVM option called “agentlib” to your startup script. On our courses, we use a bootstrap script called startup.bat, and you can edit it to look like this:

  cd ./tomcat/bin/
  java -Dsun.lang.ClassLoader.allowArraySyntax=true -agentlib:jdwp=transport=dt_socket,address=9009,server=y,suspend=n -jar bootstrap.jar
  

  
  (note: we use a simple bat file for bootstrapping Tomcat on our courses to simplify support: if you’re not using this script, then you need to put the JVM options in a new file bin/setenv.bat. Full details can be found here: )
• 2) Restart the server (in Glassfish, a link may appear at the top of the page you can click. Otherwise, run the stopserv script and then startserv)
• 3) Remember to add breakpoints in your code where required *AND re-deploy*. I sometimes forget to do this and wonder why I don’t hit any breakpoints.
• 4) Now you can attach Eclipse to the debugger:

  a) Debug icon -> Debug Configurations
  b) Click “Remote Java Application”
  c) click the tiny icon at the top left – it is for “new session”
  d) Enter the correct port number you noted earlier (we suggested 9009)
  e) click the debug button.

• 5) I find this odd: you won’t see anything special at this stage, you have attached to the running server *in the background*. There won’t be a console window and you won’t switch to debug perspective.
• 6) You now need to hit a breakpoint, so to do this, exercise your code. This may be visiting one of your webpages, or running a test harness.
• 7) When your client code causes a break to trigger on the server code, your run should be interrupted with a request to switch to the debug perspective, and you can now step through the code as usual.

I hope that’s useful!