Attach to process
IntelliJ IDEA provides a way to attach the debugger to both local and remote processes.
The steps to attach to a process depend on how and where the process was launched.
First off, if you want to debug a program that can be started from IntelliJ IDEA, the best way to do so is to start a local debugging session. This way gives you the full debugger functionality while sparing you the overhead of extra configuration.
Options described in this topic are useful in more complicated cases, such as when we need to debug a process that is running remotely, or a process that has been started in a way that does not allow for debugging.
Prerequisites
While not absolutely required, the following prerequisites have to be met to enable full-fledged debugging:
The remote process should be started with the debug agent.
The application needs to be compiled with debugging information.
You need to have sources of the application.
Debugging is still possible even when none of these are met, however, there are limitations associated with each of them. These requirements are described in more detail in subsequent chapters.
Debug agent
Processes intended to allow debugger connections are started with the debug agent. Debug agent is an entity responsible for communicating with the debugger. The debuggee communicates with IntelliJ IDEA debugger over a socket connection, irrespective of whether the process is local or remote.
Start a process with the debug agent
When starting the process, add the following line to its VM options:
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005The option has the following parameters:
address– the port that will be used for debuggingserver=y– specifies that the process should listen for incoming debugger connections (act as a server).suspend– specifies whether the process should wait until the debugger has been connected or start immediately
-agentlib:jdwp=transport=dt_socket,server=n,address=192.168.1.178:5005,suspend=y,onthrow=<FQ exception class name>,onuncaught=<y/n>The option has the following parameters:
address– the IP address and the port of the server end. Both IPv4 and IPv6 are supported.server=n– specifies that the process should connect to the debugger (act as a client)suspend=y– specifies that the process should wait until the debugger has been connected before proceeding.onthrow– optionally delays the connection until the specified exception is thrown. Exception fully-qualified name is used.onuncaught– optionally delays the connection until an uncaught exception is thrown.
The format may differ depending on the JDK version. To get an appropriately formatted string for your JDK, you can select the required JDK version in the Remote JVM debug run/debug configuration and copy it from there.
If a local process doesn't use the debug agent, you can still attach to it in the read-only mode, however the debugger functionality will be limited to viewing the call stack and examining the related local variables.
This isn't debugging in the traditional sense and should be viewed as kind of an extended thread dump. An example of the situation when it can be useful is when your program hung while batch-processing a lot of files. Using the read-only mode, you can figure out what method caused the program to hang, and which file it is processing at the moment.
Debugging information
Debugging information is special kind of information in the application bytecode. The debugger uses this information to identify local variables, line numbers, and so on. The bytecode of an application may or may not have debugging information included.
The debugging information is provided to the program at compile-time. This is controlled with the -g compiler flag. By default, the compiler includes most of the information required for debugging, but if it was not you, who compiled the application, it may happen that the program that you are going to debug was compiled without this information.
If the bytecode of the debuggee does not include debugging information, the debugger will still be able to attach, however, some of the debugger functionality may be unavailable. For example, it is not possible to view line numbers or stop at breakpoints without line number information.
The bare minimum that is always available regardless of debugging information:
Class names, unless the code is obfuscated
Static and instance variables
Call stack
For more information on how to configure debug info generation, refer to Java compiler documentation.
Application sources
It is recommended that you have the access to the sources of the project you are debugging. IntelliJ IDEA matches debugging events with the sources and displays information relevant to the debugging session in the editor. This allows you to perceive the debugging session as if it was the source code that is being executed.
For IntelliJ IDEA to find the source files, they must be located on the classpath.
Attach to a remote process
Attaching to a remote process consists of two steps:
Create a run/debug configuration – the run/debug configuration specifies how the connection should be established. Once a run/debug configuration has been created, you can reuse it for later connections.
Start the run/debug configuration – when you start the run/debug configuration, IntelliJ IDEA launches the debugger using the setup defined in the run/debug configuration.
Create a run/debug configuration
From the main menu, select . Alternatively, press Alt+Shift+F10, then 0.
In the Run/Debug Configuration dialog, click
on the toolbar or press Alt+Insert. Select Remote JVM debug from the list.In Debugger mode, specify whether the debugger should connect to the remote JVM or listen for incoming connections.
If you choose Listen to remote JVM, specify whether you want to automatically restart the debugger after the remote JVM has disconnected. This way, the debugger will always be ready to handle incoming connections.
(for Windows machines only) Optionally, specify the desired transport. IntelliJ IDEA selects the appropriate transport automatically, so you don't need to configure it unless you have special requirements regarding the communication method.
Specify the host and the port of the remote JVM. Both IPv4 and IPv6 are supported. Make sure that the port is specified correctly and is not blocked by a firewall.
Specify the module to look for the sources. IntelliJ IDEA will first check the selected module, then the other modules, if any. Sources are matched using fully-qualified class names. If there is no match by the fully-qualified name, IntelliJ IDEA tries to find a match by the file name.
If you haven't yet configured the debug agent for the debuggee JVM, you can copy the required VM option from the Command line arguments for remote JVM field.
Start the run/debug configuration
Make sure that the host application is up and running and has been started with the VM option that adds the debug agent.
Select the run/debug configuration you created earlier.
On the main toolbar, click Debug
or press Shift+F9
Attach to a local process
Press Ctrl+Alt+F5 or choose from the main menu.
IntelliJ IDEA will show the list of the running local processes. Select the process to attach to.
The processes launched with the debug agent are shown under Java. Those that don't use a debug agent are listed under Java Read Only. More on read-only mode here.
If necessary, narrow down the list of processes by typing the first letters of its name or PID.
Attach to the current process
If you run the process with the debug agent from IntelliJ IDEA, you can attach to it right from the console. It is useful in complicated workflows and situations when you don't know the debug port beforehand.
Run the process from IntelliJ IDEA with the debug agent.
When the console appears, click the Attach debugger inlay hint.
Detach from a process
The procedure to detach from a remote process is the same as for stopping a local debug session, however, the effect is different. When you detach, the debugging session closes but the process continues to run.
Click the Stop
button on the main toolbar on in the Debug tool window.
Alternatively, click Stop
on the main toolbar or press Ctrl+F2, then select the session to be closed.