Chapter 6. Debugging your Spring Boot-based application

This sections contains information about debugging your Spring Boot–based application both in local and remote deployments.

6.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.

6.1.1. Starting your Spring Boot 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 when launching the application manually using the mvn spring-boot:run goal.

Prerequisites

  • A Maven-based application

Procedure

  1. In a console, navigate to the directory with your application.
  2. Launch your application and specify the necessary JVM arguments and the debug port using the following syntax:

    $ mvn spring-boot:run -Drun.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=$PORT_NUMBER"

    $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 to y.

6.1.2. Starting an uberjar in debugging mode

If you chose to package your application as a Spring Boot uberjar, debug it by executing it with the following parameters.

Prerequisites

  • An uberjar with your application

Procedure

  1. In a console, navigate to the directory with the uberjar.
  2. 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 to y.

6.1.3. Starting your application on OpenShift in debugging mode

To debug your Spring Boot-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

  1. Using the oc command, list the available deployment configurations:

    $ oc get dc
  2. Set the JAVA_DEBUG environment variable in the deployment configuration of your application to true, which configures the JVM to open the port number 5005 for debugging. For example:

    $ oc set env dc/MY_APP_NAME JAVA_DEBUG=true
  3. Redeploy the application if it is not set to redeploy automatically on configuration change. For example:

    $ oc rollout latest dc/MY_APP_NAME
  4. Configure port forwarding from your local machine to the application pod:

    1. 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
      ...
    2. 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.

  5. 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.

6.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

  1. Start Red Hat CodeReady Studio.
  2. Create a new debug configuration for your application:

    1. Click Run→Debug Configurations.
    2. In the list of configurations, double-click Remote Java application. This creates a new remote debugging configuration.
    3. Enter a suitable name for the configuration in the Name field.
    4. Enter the path to the directory with your application into the Project field. You can use the Browse…​ button for convenience.
    5. Set the Connection Type field to Standard (Socket Attach) if it is not already.
    6. Set the Port field to the port number that your application is listening on for debugging.
    7. Click Apply.
  3. 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

6.2. Debug logging

6.2.1. Add Spring Boot debug logging

Add debug logging to your application.

Prerequisites

Procedure

  1. Declare a org.apache.commons.logging.Log object using the org.apache.commons.logging.LogFactory for the class you want to add logging.

    import org.apache.commons.logging.Log;
    import org.apache.commons.logging.LogFactory;
    ...
    private static Log logger = LogFactory.getLog(TheClass.class);

    For example, if you wanted to add logging to the GreetingEndpoint class in the REST API Level 0 example, you would use GreetingEndpoint.class.

  2. Add debugging statements using logger.debug("my logging message").

    Example logging statement

    @GET
    @Path("/greeting")
    @Produces("application/json")
    public Greeting greeting(@QueryParam("name") @DefaultValue("World") String name) {
        String message = String.format(properties.getMessage(), name);
    
        logger.debug("Message: " + message);
    
        return new Greeting(message);
    }

  3. Add a logging.level.fully.qualified.name.of.TheClass=DEBUG in src/main/resources/application.properties.

    For example, if you added a logging statement to io.openshift.booster.service.GreetingEndpoint you would use:

    logging.level.io.openshift.booster.service.GreetingEndpoint=DEBUG

    This enables log messages at the DEBUG level and above to be shown in the logs for your class.

6.2.2. Accessing Spring Boot debug logs on localhost

Start your application and interact with it to see the debugging statements.

Prerequisites

  • An application with debug logging enabled.

Procedure

  1. Start your application.

    $ mvn spring-boot:run
  2. Test your application to invoke debug logging.

    For example, to test the REST API Level 0 example, you can invoke the /api/greeting method:

    $ curl http://localhost:8080/api/greeting?name=Sarah
  3. View your application logs to see your debug messages.

    i.o.booster.service.GreetingEndpoint     : Message: Hello, Sarah!

To disable debug logging, remove logging.level.fully.qualified.name.of.TheClass=DEBUG from src/main/resources/application.properties and restart your application.

6.2.3. 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

  1. Deploy your application to OpenShift:

    $ mvn clean fabric8:deploy -Popenshift
  2. View the logs:

    1. Get the name of the pod with your application:

      $ oc get pods
    2. 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.

  3. 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:

    1. Get the route of your application:

      $ oc get routes
    2. Make an HTTP request on the /api/greeting endpoint of your application:

      $ curl $APPLICATION_ROUTE/api/greeting?name=Sarah
  4. Return to the window with your pod logs and inspect debug logging messages in the logs.

    i.o.booster.service.GreetingEndpoint     : Message: Hello, Sarah!
  5. To disable debug logging, remove logging.level.fully.qualified.name.of.TheClass=DEBUG from src/main/resources/application.properties and redeploy your application.