How to Debug a Remote Java Application

The importance of being able to debug a Java application that is deployed remotely, in another country or city, cannot be understated. Recently, I was working with a Java application that was bugging me when it was running in another country (USA), but it works fine when I run it on my desktop here in India. Of course, there is no connection with the geography except that the connection is slower. Every time I had a problem which is time-consuming to reproduce on my desktop; I would log in to that computer remotely through VNC client, reproduce the problem, get the logs, diagnose, and test it again there. You may ask, "Why don't you create a similar setup of that remote machine next to your desktop?" Trust me, there's a reason why I can't do it and I won't have a setup anytime sooner. Don't let that distract you about what I am trying to say, just forget it and assume I have to test it on a remote machine that resides in the same Intranet.

I was a having a conversation with one of my coworkers on phone about a particular problem and he said, "It will be slow but why don't you debug and see it?" My face turned red and I felt a little ashamed; I knew what he was talking about. He is a smart guy. I knew for sure he was not asking me to switch my whole development environment to some remote machine sitting on the other side of the globe. I hung up the phone, I walked to his desk and asked him. "Did you say debug?" He generously showed me how to do it. In fact, he thought that I don't know what is debugging and he explained me everything — all that Step-Into, Step-Over, Step-Out stuff with its shortcuts.

It was easy for me to jump and say, "Dude! I know how to debug!" but that would have been a wrong thing to do at that time. I know many people who come for help to me do this. So I quietly listened to him and gently said, "Yep, I'm familiar with that."

In case you have never done this before — here is how you do it. I will show how to do this using the Eclipse IDE, and I am very sure you are smart enough to figure out for your development setup.

Let's say you have your application compiled into a jar called myapp.jar and this will be running remotely on a machine called myremote.mycompany.com (or some IP). Your development machine is mydevel.mycompany.com. Now to debug the myapp.jar that is running remotely from your desktop machine, there are two steps you have to follow:

1. Start the application and tell the JVM that it will be debugged remotely
2. Configure your IDE on your desktop to be able to debug that remote application

Starting the Application With Remote Debugging Enabled

 java -Xdebug -Xrunjdwp:transport=dt_socket,address=8998,server=y -jar myapp.jar

The above command says: start myapp.jar + start a server socket at port 8998 and publish the debugging messages using the Java Debug Wire Protocol (jdwp) there.

Other than address, server, and transport, there are other sub-options available for  -Xrunjdwp option — for example: suspend. I will leave that for you. Let's move on to step 2, that is configuring Eclipse.

Configuring Eclipse to Debug a Remotely Running Application

I will just show the screenshots without writing much, it's just intuitive that way.

1. Start Eclipse
2. Go to Run -> Debug Configurations
3. Create a new Remote Java Application configuration
4. Configure the remote application's details
5. If you would like to have this launch configuration in your favorites menu
6. Don't forget to click Apply

Cool, isn't it? That it.

Originally published August 2015