Search

Chapter 3. Debugging your Node.js based application

download PDF

This section contains information about debugging your Node.js–based application and using debug logging in both local and remote deployments.

3.1. Remote debugging

To remotely debug an application, you need to start it in a debugging mode and attach a debugger to it.

3.1.1. Starting your application locally and attaching the native debugger

The native debugger enables you to debug your Node.js–based application using the built-in debugging client.

Prerequisites

  • An application you want to debug.

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.

  2. Use the debugger prompt to perform debugging commands.

3.1.2. Starting your application locally and attaching the V8 inspector

The V8 inspector enables you to debug your Node.js–based application using other tools, such as Chrome DevTools, that use the Chrome Debugging Protocol.

Prerequisites

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.

  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.

3.1.3. Starting your application on OpenShift in debugging mode

To debug your Node.js-based application on OpenShift remotely, you must set the NODE_ENV environment variable inside the container to development 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.
  • 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 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-

3.2. Debug logging

Debug logging is a way to add detailed information to the application log when debugging. This allows you to:

  • Keep minimal logging output during normal operation of the application for improved readability and reduced disk space usage.
  • View detailed information about the inner workings of the application when resolving issues.

3.2.1. Add debug logging

This example uses the debug package, but there are also other packages available that can handle debug logging.

Prerequisites

  • You have an application that you want to debug.

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.

  4. Install the application dependencies.

    $ npm install

3.2.2. Accessing debug logs on localhost

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

Prerequisites

  • An application with debug logging.

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, the following command is based on an example REST API level 0 application where debug logging 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

3.2.3. Accessing Node.js debug logs on OpenShift

Use the the DEBUG environment variable in your application pod in OpenShift to enable debug logging.

Prerequisites

  • An application with debug logging.
  • The oc CLI client installed.

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, the following command is based on an example REST API level 0 application where debug logging is set 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

To disable debug logging, remove the DEBUG environment variable from the pod:

$ oc set env dc DC_NAME DEBUG-

Additional resources

More details on environment variables are available in the OpenShift documentation.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.