jetty-documentation/src/main/asciidoc/reference/debugging/enable-remote-debugging.adoc

//  ========================================================================
//  Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[enable-remote-debugging]]
=== Enable remote debugging

[[remote-debugging]]
==== Remote Debugging

If you have a web application deployed into Jetty you can interact with it remotely from a debugging perspective easily.
The basics are that you must start up the remote JVM with additional parameters and then start up a remote debugging session in Eclipse for the webapp in question.
This is easily accomplished.

____
[NOTE]
This example assumes you are deploying your web application into the jetty-distribution.
____

===== Starting Jetty

Assuming you have your webapp deployed into jetty, there are two different ways to approach this:

Via command line::
  Add the required parameters on the commandline like so.
+
[source, screen, subs="{sub-order}"]
....
                            
$ java -Xdebug -agentlib:jdwp=transport=dt_socket,address=9999,server=y,suspend=n -jar start.jar

                        
....

Via `start.ini`::
  This approach is best used if you want to debug a particular jetty-distribution and not have to remember the commandline incantations.
+
1.  Edit the `start.ini` and uncomment the --exec line, this is required if you are adding jvm options to the start.ini file as jetty-start must generate the classpath required and fork a new jvm.
2.  Add the parameters mentioned above in the Command Line option so your start.ini looks like this:
+
[source, plain, subs="{sub-order}"]
----
#===========================================================
# Configure JVM arguments.
# If JVM args are include in an ini file then --exec is needed
# to start a new JVM from start.jar with the extra args.
# If you wish to avoid an extra JVM running, place JVM args
# on the normal command line and do not use --exec
#-----------------------------------------------------------
--exec
-Xdebug
-agentlib:jdwp=transport=dt_socket,address=9999,server=y,suspend=n
# -Xmx2000m
# -Xmn512m
# -XX:+UseConcMarkSweepGC
# -XX:ParallelCMSThreads=2
# -XX:+CMSClassUnloadingEnabled
# -XX:+UseCMSCompactAtFullCollection
# -XX:CMSInitiatingOccupancyFraction=80
# -verbose:gc
# -XX:+PrintGCDateStamps
# -XX:+PrintGCTimeStamps
# -XX:+PrintGCDetails
# -XX:+PrintTenuringDistribution
# -XX:+PrintCommandLineFlags
# -XX:+DisableExplicitGC

                                    
----
+
Uncomment any other jvm environmental options you so desire for your debugging session.

3.  Regardless of the option chosen, you should see the following lines at the top of your jetty-distribution startup.
+
[source, plain, subs="{sub-order}"]
----
Listening for transport dt_socket at address: 9999

----

===== Linking with your IDE

Refer to the documentation for your ide:

* xref:debugging-with-intellij[]
* xref:debugging-with-eclipse[]