-
Language:
English
-
Language:
English
Chapter 11. Debugging your application
This sections contains information about debugging your Thorntail–based application both in local and remote deployments.
11.1. Remote debugging
To remotely debug an application, you must first configure it to start in a debugging mode, and then attach a debugger to it.
11.1.1. Starting your application locally in debugging mode
One of the ways of debugging a Maven-based project is manually launching the application while specifying a debugging port, and subsequently connecting a remote debugger to that port. This method is applicable at least to the following deployments of the application:
-
When launching the application manually using the
mvn thorntail:run
goal. -
When starting the application without waiting for it to exit using the
mvn thorntail:start
goal. This is useful especially when performing integration testing. - When using the Arquillian adapter for Thorntail.
Prerequisites
- A Maven-based application
Procedure
- In a console, navigate to the directory with your application.
Launch your application and specify the debug port using the
-Dthorntail.debug.port
argument:$ mvn thorntail:run -Dthorntail.debug.port=$PORT_NUMBER
Here,
$PORT_NUMBER
is an unused port number of your choice. Remember this number for the remote debugger configuration.
11.1.2. Starting an uberjar in debugging mode
If you chose to package your application as a Thorntail uberjar, debug it by executing it with the following parameters.
Prerequisites
- An uberjar with your application
Procedure
- In a console, navigate to the directory with the uberjar.
Execute the uberjar with the following parameters. Ensure that all the parameters are specified before the name of the uberjar on the line.
$ java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=$PORT_NUMBER -jar $UBERJAR_FILENAME
$PORT_NUMBER
is an unused port number of your choice. Remember this number for the remote debugger configuration.If you want the JVM to pause and wait for remote debugger connection before it starts the application, change
suspend
toy
.
Additional resources
11.1.3. Starting your application on OpenShift in debugging mode
To debug your Thorntail-based application on OpenShift remotely, you must set the JAVA_DEBUG
environment variable inside the container to true
and configure port forwarding so that you can connect to your application from a remote debugger.
Prerequisites
- Your application running on OpenShift.
-
The
oc
binary installed on your machine. -
The ability to execute the
oc port-forward
command in your target OpenShift environment.
Procedure
Using the
oc
command, list the available deployment configurations:$ oc get dc
Set the
JAVA_DEBUG
environment variable in the deployment configuration of your application totrue
, which configures the JVM to open the port number5005
for debugging. For example:$ oc set env dc/MY_APP_NAME JAVA_DEBUG=true
Redeploy the application if it is not set to redeploy automatically on configuration change. For example:
$ oc rollout latest dc/MY_APP_NAME
Configure port forwarding from your local machine to the application pod:
List the currently running pods and find one containing your application:
$ oc get pod NAME READY STATUS RESTARTS AGE MY_APP_NAME-3-1xrsp 0/1 Running 0 6s ...
Configure port forwarding:
$ oc port-forward MY_APP_NAME-3-1xrsp $LOCAL_PORT_NUMBER:5005
Here,
$LOCAL_PORT_NUMBER
is an unused port number of your choice on your local machine. Remember this number for the remote debugger configuration.
When you are done debugging, unset the
JAVA_DEBUG
environment variable in your application pod. For example:$ oc set env dc/MY_APP_NAME JAVA_DEBUG-
Additional resources
You can also set the JAVA_DEBUG_PORT
environment variable if you want to change the debug port from the default, which is 5005
.
11.1.4. Attaching a remote debugger to the application
When your application is configured for debugging, attach a remote debugger of your choice to it. In this guide, Red Hat CodeReady Studio is covered, but the procedure is similar when using other programs.
Prerequisites
- The application running either locally or on OpenShift, and configured for debugging.
- The port number that your application is listening on for debugging.
- Red Hat CodeReady Studio installed on your machine. You can download it from the Red Hat CodeReady Studio download page.
Procedure
- Start Red Hat CodeReady Studio.
Create a new debug configuration for your application:
- Click Run→Debug Configurations.
- In the list of configurations, double-click Remote Java application. This creates a new remote debugging configuration.
- Enter a suitable name for the configuration in the Name field.
- Enter the path to the directory with your application into the Project field. You can use the Browse… button for convenience.
- Set the Connection Type field to Standard (Socket Attach) if it is not already.
- Set the Port field to the port number that your application is listening on for debugging.
- Click Apply.
Start debugging by clicking the Debug button in the Debug Configurations window.
To quickly launch your debug configuration after the first time, click Run→Debug History and select the configuration from the list.
Additional resources
Debug an OpenShift Java Application with JBoss Developer Studio on Red Hat Knowledgebase.
Red Hat CodeReady Studio was previously called JBoss Developer Studio.
- A Debugging Java Applications On OpenShift and Kubernetes article on OpenShift Blog.
11.2. Debug logging
11.2.1. Local debug logging
To enable debug logging locally, see the Section 7.1, “Enabling logging” section and use the DEBUG
log level.
If you want to enable debug logging permanently, add the following configuration to the src/main/resources/project-defaults.yml
file in your application:
Debug logging YAML configuration
swarm: logging: DEBUG
11.2.2. Accessing debug logs on OpenShift
Start your application and interact with it to see the debugging statements in OpenShift.
Prerequisites
- A Maven-based application with debug logging enabled.
-
The
oc
CLI client installed and authenticated.
Procedure
Deploy your application to OpenShift:
$ mvn clean fabric8:deploy -Popenshift
View the logs:
Get the name of the pod with your application:
$ oc get pods
Start watching the log output:
$ oc logs -f pod/MY_APP_NAME-2-aaaaa
Keep the terminal window displaying the log output open so that you can watch the log output.
Interact with your application:
For example, if you had debug logging in the REST API Level 0 example to log the
message
variable in the/api/greeting
method:Get the route of your application:
$ oc get routes
Make an HTTP request on the
/api/greeting
endpoint of your application:$ curl $APPLICATION_ROUTE/api/greeting?name=Sarah
Return to the window with your pod logs and inspect debug logging messages in the logs.
... 2018-02-11 11:12:31,158 INFO [io.openshift.MY_APP_NAME] (default task-18) Hello, Sarah! ...
-
To disable debug logging, remove the
logging
key from theproject-defaults.yml
file and redeploy the appliation.
Additional resources