Monday, 22 January 2018

Eclipse IDE - How to Remote Debug a Java Application Running on Linux

The remote debugging of Java program is an ultimate tool in the arsenal of a Java developer, which is often become the last and only tool to investigate a bug on a Java application running on remote host e.g. on Linux server or Windows server. Almost all major Java IDE provides remote debugging e.g. NetBeans, Eclipse, and IntelliJ IDEA, but I mostly use Eclipse for Java coding and so it's my preferred tool to remote debug a Java program. In order to setup remote debugging in Eclipse, you need to do a couple of tasks e.g. you need to start your JVM with debugging parameters or arguments and then you need to create a "remote debug configuration" in Eclipse IDE itself.

I have sharing Eclipse a lot of tips and tricks in this blog e.g. escaping JSON string in Eclipse to easily create JSON for testing and debugging purpose and In this article, I'll walk you through all the steps required to setup remote debugging in Eclipse and how to debug a Java program running on a remote Linux server.

I'll also tell you how to use essential debugging commands e.g. Step Into, Step Over, and how to watch variables while debugging, which will not only helpful during remote debugging but also on during local debugging, right from Eclipse.

Btw, before starting this tutorial, I expect that you are familiar with both Java, JVM, and Eclipse IDE itself because when we talk about Run and Debug configuration, you should understand what we are talking about.  I'll show you the screenshot but basic knowledge of Eclipse will help.

If you are complete beginner then I suggest you to first go through Beginners Eclipse Java IDE Training Course before starting with remote debugging. That will help you to use Eclipse IDE effectively for Java development.

Steps to remote debug a Java appliation in Eclipse IDE


1) Start JVM with debug arguments

In order to debug a Java application running on a remote host(Linus or Windowx), you first need to start the JVM with debugging arguments, as shown by following command:

$ /oracle/jre/v1.6.0_18-64bit/bin/java -Xdebug -Xrunjdwp:transport=dt_socket,address=11001,server=y,suspend=y -jar app.jar

Though there are different JVM options to start your JVM in debug mode, depending upon which version of JRE you are using.

If you're using Java 1.4 JRE then you need to use -Xdebug and -Xrunjdwp arguments. These options will also work in later versions, but it will run in interpreted mode instead of JIT, which will be slower.

Btw, I really hope Eclipse should have something similar to IntelliJ IDEA which makes it easy to remember the JVM debugging options as shown below:

Oracle Java Tutorials and Materials, Oracle Java Certifications

From Java 5.0, it is better to use the -agentlib:jdwp as single option e.g. :

$ java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=11001

Options on -Xrunjdwp or agentlib:jdwp arguments are almost same:

transport=dt_socket: means the way used to connect to JVM (socket is a good choice, it can be used to debug a distant computer)

address=11001: TCP/IP port exposed, to connect from the debugger,

suspend=y: if 'y', tell the JVM to wait until the debugger is attached to begin execution, otherwise (if 'n'), starts execution right away.

If you are debugging for an event which happens during startup then you can use the suspend="y" to go through startup sequence step by step. On the other hand, if the issue is happening after it receives a message or request then you can start with suspend="n" and connect it later. 

Oracle Java Tutorials and Materials, Oracle Java Certifications

2) Create a Remote Debug Configuration in Eclipse IDE

You also need to create a remote debug configuration in Eclipse IDE before you start debugging. In order to do so, just follow steps:

2.1) Go to debug configuration from Run menu as shown below:

Oracle Java Tutorials and Materials, Oracle Java Certifications

2.2) Go to remote Java application

2.3) Configure details e.g. name, project, the Eclipse project which contains the code of Java application you are trying to debug. Connection type should be "socket attach" and then specify host and port in Connection properties as shown below. Always specify fully qualified domain name for the host

2.4) Hit apply after making change

Oracle Java Tutorials and Materials, Oracle Java Certifications

You are done with setting up remote debugging in Eclipse. In the next part of this article, I'll show you how to remote debug a Java application step by step.

How to remote debug Java application in Eclipse


Once you are done with setting up remote debugging in Eclipse IDE, you can follow these steps to start debugging your remote Java program:

1. Setup a Breakpoint  in Your Code

In order to start debugging, you first need to setup breakpoint in your code. You can setup breakpoint at any line by the just left click of mouse i.e. go to your Java code and left click on any line where you want to stop the JVM.

This is also known as line breakpoint, btw, don't put line breakpoint on empty lines. Also, if you are just starting with debugging, you can start with putting a breakpoint in the main() method which is the entry point of Java application.

Oracle Java Tutorials and Materials, Oracle Java Certifications

2. Start JVM with Debug Arguments

Before you launch your Eclipse remote debugging configuration, you need to start the JVM on the remote host as shown in following command:

$ /oracle/jre/v1.6.0_18-64bit/bin/java -Xdebug -Xrunjdwp:transport=dt_socket,address=11001,server=y,suspend=y -jar app.jar

A couple of things to note here, we are starting JVM on server mode and asking it to suspend until the debugger connects it, which means it will not start execution until you start your Eclipse IDE and launch remote debug.

It is also listening for the debugger on port 11001, which means your Eclipse remote debugging setting should also use the same port.

Once you start the JVM, it will print the following line the log file or command line, depending upon where you are redirecting the output stream:

Listening for transport dt_socket at address: 11001

This means JVM is ready to attach the debugger and now it's time to start remote debugging in Eclipse IDE.

3. Launch your Remote Debug Configuration in Eclipse

Once JVM is started in debug mode and you can see the above line the log file, you can just go and launch the remote debug configuration and double-clicking the configuration you have just created. If JVM is running then it will try to connect it using host and port details given in the configuration i.e. 1001 but if JVM is not running then it will show following error:

Oracle Java Tutorials and Materials, Oracle Java Certifications

This error means either your JVM is not running but if you are sure that JVM is indeed started and ready to connect then maybe your host and port configuration is incorrect e.g. any typo on fully qualified domain name or any network issue which preventing your local machine to connect to the remote host.

If your Eclipse IDE is successful to establish a connection to debugger running on remote JVM then Eclipse will open debug perspective and you could see where exactly JVM has stopped, a full stack trace starting from loading the classes. Now, you got the control of flight and it's up to you how you move.

When you first time debugs a Java program, Eclipse will ask you open the Debug Perspective and then next time it will automatically do so.

Here is how Eclipse' Debug Perspective look like:

Oracle Java Tutorials and Materials, Oracle Java Certifications

In Debug Perspective, you have a lot of debugging tools e.g. you can execute code step by step, can see where you have put breakpoints, can watch values of variables and can see which thread you are debugging and can terminate the debugging session. The debug perspective is same for both local and remote debugging.

4. Move Step by Step in your Java Code

There are a couple of option to move in your code you can use either Step Into for step by step executing code, which means if the code contains a method call then your code will go inside a method and then initialize variable and other code and finally come back to where you were.

Oracle Java Tutorials and Materials, Oracle Java Certifications

Alternatively, you can use Step Over to just go over the method call and move to the new line. You can use a combination of these two commands to effectively move around interested read to find any bug or observer the output in the log file. The button to Step Over is just next to Step Into as seen in above screenshot.

5. Watch values of Variables

While remote debugging your Java application you can also see values of a local variable and member variables into "Variables" window as shown in the following screenshot. 
Oracle Java Tutorials and Materials, Oracle Java Certifications

This is very useful to find out any inconsistency between expected and actual values.  You can also add a variable to watch window to periodically check its value.

6. Terminate the JVM

Once you are done with remote debugging and find the root cause of your problem you can terminate the remote Java application right from the Eclipse IDE. This will stop the JVM as well Eclipse remote debug console.


That's all about how to setup remote debugging in Eclipse IDE and how to remote debug a Java application running on Linux server. The key is that you should have the same version of a class file and Java source file on both remote and local machine.

If your Java source code is not in sync with the class file on remote host then the debugging will be inaccurate i.e. you will set a breakpoint at line 5 but your code will be running line 10, hence it is an absolute must that both code and binary running on the remote host must be of the same version.

Related Posts