Module 1: Remote Debugging

Overview of Remote Debugging

Basic Concepts

Up until now, we have been running our application and debugger under the same IDE (IntelliJ) session:

While this is great when developing an application, it is not the environment where the application will run after it is deployed (production environment). Occasionally programs operate differently in a production environment than in the development environment. These differences in operation can occur for several reasons: varied hardware configurations, connections to different resources, leveraging resources unavailable in development, different runtime environment/software versions, et al.

Debugging or monitoring an application in its production environment allows us to see how/if it operates as intended.

With remote debugging, we can connect the debugger in our IDE (IntelliJ) to a process running outside the IDE on a different computer/server or our local machine:

With the remote debugging features of your favorite IDE, you can attach to an application running outside your IDE -- even on another computer -- and set up breakpoints and inspect application state just like you would when running code from within the IDE.

To set up remote debugging, you first must configure the application and debugger to allow for remote debugging.

For the application:

• Compile the application with debug information.
• Start the application in the Java JVM with debugging options (more about this later).

For the debugger:

• Know the location of the application class file from the build process.
• Know the port you want to use for debugging. When connecting to external applications, make sure the port is not already in use. 5005 is a commonly used port for remote debugging and the one we will be using.

Starting a non-server application for debugging in the Java JVM

To perform remote debugging for a non-server Java application, you must start the application in the Java JVM with the appropriate debugging options.

The command to start an application in the JVM for debugging is:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:port application-class-name

where:

• java - name of command to invoke the Java JVM
• -agentlib:jdwp - indicates you will use the Java Debug Wire Protocol to communicate with the JVM for debugging
• transport=dt_socket - indicates the JVM for will use a socket stream to transport information to/from the debugger
• server=y - indicates the JVM will function as a server for the remote debugging purposes
• suspend=n - indicates process is to start normally and not suspend execution before it starts
• address=*:port - specifies the port the JVM will listen to remote debugging
• application-class-name - the name of the application .class file containing the main() function for the application

Setting up a debugging run configuration in an IDE

Every robust IDE will have a method for connecting to a remote (external) process for debugging.

The details and actual process and parameters will vary from IDE to IDE, but in general, will include the following generic setup:

• Create a project for the remote debugging session.
• Create a Run/Debug configuration for remote debugging that includes:
  • Debugging mode
  • Host/Server name of the external process
  • Port that the external process will be listening to
  • Path to the source code of the external process, if available
  • Additional information required by the particular IDE

Performing remote debugging

1. Start the process to be remotely debugged. If the process is not on an actual server, use the JVM command with the appropriate options from a command line. You should see an indication that the JVM is listening for a remote debugger. The message may look something like this:

   Listening for transport dt_socket at address: nnnn <=== this should be the port you specified in the JVM command

2. Open the remote debugging project in the IDE.
3. Start the debugger in the IDE.

You should now be in remote debugging mode. Most debuggers will issue a message in the console window indicating they have attached themselves to an external task. The message may look something like this:

Connected to the target VM, address: 'servername:port', transport: 'socket'

Congratulations!

You are now connected to an external process from your IDE debugger. You can start swatting bugs, set breakpoints, examine/change variables, just "poke around," or perform whatever other debugging you need to do.

The first command you might want to try is to pause the external process so you can interact with it.

Note: You may need to change to the "Debugger" window/tab in the IDE to see the results of your debugging efforts.

When you have finished debugging:

• Terminate the debugging session in the IDE.
• Go to the command window and terminate the application. Usually, you can accomplish this by pressing the control-C keys.
• If you do not terminate the application, it will continue to run to normal completion or until you close the command window. To avoid potential resource leaks, you will want (and it is considered good practice) to terminate the application before closing the command window.

Guided Projects