Chapter 4. Debugging your Node.js based application

Procedure

1. Start the application with the debugger enabled.

   The native debugger is automatically attached and provides a debugging prompt.

   Example application with the debugger enabled

   $ node inspect app.js
   < Debugger listening on ws://127.0.0.1:9229/12345678-aaaa-bbbb-cccc-0123456789ab
   < For help see https://nodejs.org/en/docs/inspector
   < Debugger attached.
   ...
   debug>

   If you have a different entry point for your application, you need to change the command to specify that entry point:

   $ node inspect path/to/entrypoint

   For example, when using the express generator to create your application, the entry point is set to ./bin/www by default. Some of the examples, such as the REST API Level 0 example application, use ./bin/www as an entry point.

2. Use the debugger prompt to perform debugging commands.

Procedure

1. Start your application with the V8 inspector integration enabled.

   $ node --inspect app.js

   If you have a different entry point for your application, you need to change the command to specify that entry point:

   $ node --inspect path/to/entrypoint

   For example, when using the express generator to create your application, the entry point is set to ./bin/www by default. Some of the examples, such as the REST API Level 0 example application, use ./bin/www as an entry point.

2. Attach the V8 inspector and perform debugging commands.

   For example, if using Google Chrome:

   1. Navigate to chrome://inspect.
   2. Select your application from below Remote Target.
   3. You can now see the source of your application and can perform debugging actions.

Procedure

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

   $ oc get dc

2. Set the NODE_ENV environment variable in the deployment configuration of your application to development to enable debugging. For example:

   $ oc set env dc/MY_APP_NAME NODE_ENV=development

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:5858

      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. Attach the V8 inspector and perform debugging commands.

   For example, if using Google Chrome:

   1. Navigate to chrome://inspect.
   2. Click Configure.
   3. Add 127.0.0.1:$LOCAL_PORT_NUMBER.
   4. Click Done.
   5. Select your application from below Remote Target.
   6. You can now see the source of your application and can perform debugging actions.

6. When you are done debugging, unset the NODE_ENV environment variable in your application pod. For example:

   $ oc set env dc/MY_APP_NAME NODE_ENV-

Procedure

1. Add the debug logging definition.

   const debug = require('debug')('myexample');

2. Add debug statements.

   app.use('/api/greeting', (request, response) => {
     const name = request.query ? request.query.name : undefined;
     //log name in debugging
     debug('name: '+name);
     response.send({content: `Hello, ${name || 'World'}`});
   });

3. Add the debug module to package.json.

   ...
   "dependencies": {
       "debug": "^3.1.0"
     }

   Depending on your application, this module may already be included. For example, when using the express generator to create your application, the debug module is already added to package.json. Some of the example applications, such as the REST API Level 0 example, already have the debug module in the package.json file.

4. Install the application dependencies.

   $ npm install

Procedure

1. Set the DEBUG environment variable when starting your application to enable debug logging.

   $ DEBUG=myexample npm start

   The debug module can use wildcards to filter debugging messages. This is set using the DEBUG environment variable.

2. Test your application to invoke debug logging.

   For example, when debug logging in the REST API Level 0 example is set to log the name variable in the /api/greeting method:

   $ curl http://localhost:8080/api/greeting?name=Sarah

3. View your application logs to see your debug messages.

   myexample name: Sarah +3m

Procedure

1. Use the oc CLI client to log into your OpenShift instance.

   $ oc login ...

2. Deploy your application to OpenShift.

   $ npm run openshift

   This runs the openshift npm script, which wraps direct calls to nodeshift.

3. Find the name of your pod and follow the logs to watch it start.

   $ oc get pods
   ....
   $ oc logs -f pod/POD_NAME

   Important

   After your pod has started, leave this command running and execute the remaining steps in a new terminal window. This allows you to follow the logs and see new entries made to it.

4. Test your application.

   For example, if you had debug logging in the REST API Level 0 example to log the name variable in the /api/greeting method:

   $ oc get routes
   ...
   $ curl $APPLICATION_ROUTE/api/greeting?name=Sarah

5. Return to your pod logs and notice there are no debug logging messages in the logs.

6. Set the DEBUG environment variable to enable debug logging.

   $ oc get dc
   ...
   $ oc set env dc DC_NAME DEBUG=myexample

7. Return to your pod logs to watch the update roll out.

   After the update has rolled out, your pod will stop and you will no longer be following the logs.

8. Find the name of your new pod and follow the logs.

   $ oc get pods
   ....
   $ oc logs -f pod/POD_NAME

   Important

   After your pod has started, leave this command running and execute the remaining steps in a different terminal window. This allows you to follow the logs and see new entries made to it. Specifically, the logs will show your debug messages.

9. Test the application to invoke debug logging.

   $ oc get routes
   ...
   $ curl $APPLICATION_ROUTE/api/greeting?name=Sarah

10. Return to your pod logs to see the debug messages.

    ...
    myexample name: Sarah +3m