Java remote debugging, how does it work technically?

The debugging features of the JVM are provided via the Java Platform Debugger Architecture (JPDA).

The JPDA itself is composed of the following:

  • Java Virtual Machine Tool Interface (JVM TI) - the native programming interface for tools to use. This interface allows for state inspection and helps in controlling the flow of execution within the debuggee.
  • Java Debug Wire Protocol (JDWP) - used to define the communication between the debugger and debuggee processes.
  • Java Debug Interface (JDI) - this interface allows tool developers to write remote debugger applications.

The diagram listed in the JPDA architecture structure is a good starting point. Additional places to look for would be the guides listed in the JPDA page.


Eclipse debugging starts with what is referred to as Agents.

The JVM, which runs the complied ".class" sources has a feature that allows external libraries (written in Java or C++) to be injected into the JVM, during runtime. These external libraries are referred to as Agents and they have the ability to modify the content of the .class files been run. These Agents have access to functionality of the JVM that is not accessible from within a regular Java code running inside the JVM and they can be used to do interesting stuff like injecting and modify the running source code, profiling etc. Some tools like JRebel(used for hot replacement of code) makes use of this piece of functionality to achieve their magic.

And to pass an Agent Lib to a JVM, you do so via start up arguments, using the -

agentlib:libname[=options]

We were actually passing an Agent Lib named jdwp to the JVM running Tomcat. The jdwp is a JVM specific, optional implementation of the JDWP (Java Debug Wire Protocol) that is used for defining communication between a debugger and a running JVM. It’s implementation, if present is supplied as a native library of the JVM as either jdwp.so or jdwp.dll

So what does it do? In simple terms, the jdwp agent we pass is basically serving the function of being a link between the JVM instance running an application and a Debugger (which can be located either remote or local). Since it is an Agent Library, It does have the ability to intercept the running code, create a bridge between the JVM and a debugger, and have the functionality of a debugger applied on the JVM. Since in the JVM architecture, the debugging functionality is not found within the JVM itself but is abstracted away into external tools (that are aptly referred to as debuggers), these tools can either reside on the local machine running the JVM being debugged or be run from am external machine. It is this de-coupled, modular architecture that allows us to have a JVM running on a remote machine and using the JDWP, have a remote debugger be able to communicate with it.

That is how Eclipse debugger works in short.


Java's debugging architecture is called JPDA. You probably want to read the JPDA documentation. In particular, the Walk-through section gives an example of an IDE interfacing with the JDI to obtain a value on the stack.