Set Up Remote Debugging to Diagnose CAP Applicatio...

Arley-Triana-Morin · ‎2021 Jun 11

Introduction

In this blog post, we will explore the process of setting up remote debugging for a deployed CAP (Cloud Application Programming) application instance running on the SAP BTP (Business Technology Platform) in a Cloud Foundry environment. Remote debugging is a valuable tool for developers when troubleshooting misbehaving applications, especially when analysis of logs or local testing fails to reproduce runtime errors.

Enabling remote debugging allows developers to leverage their local development environment to inspect and interact with the application, allowing for efficient problem diagnosis.

Disclaimer: It isn't advisable to enable remote debugging for an application running on production.

The key topics covered in this article include:

Authenticating to Cloud Foundry with the Command Line Interface (CLI)
Connecting to a Cloud Foundry application instance using the Secure Shell (SSH) protocol
Enabling the Node.js inspector for remote debugging on a running application instance
Enabling port forwarding to Cloud Foundry
Attaching a Node.js debugger to a process running on a Cloud Foundry application instance

Step 1: Install and Verify the Cloud Foundry Command Line Interface (CLI) Installation

To begin, we need to install the Cloud Foundry CLI. Follow the official guide for installation instructions, which provides detailed steps tailored to your operating system.

Once the installation is complete, we can verify it by performing the following steps:

Open a new command prompt session or terminal.
Run the following command:

cf -v

If the installation is successful, the Cloud Foundry CLI version will be displayed in the standard output. For example:

cf version 7.2.0+be4a5ce2b.2020-12-10

Step 2: Log In to the Cloud Foundry Instance with the CLI and SAP Single Sign-On

To log in to the Cloud Foundry account, the `cf login` command is used.

cf login [-a API_URL] [-o ORG] [-s SPACE] [--sso]

Where:

API-URL is your API endpoint (for example, https://api.cf.eu20.hana.ondemand.com).
ORG is the org name where your application is deployed. Orgs map to business units have quota plans and unique roles.
SPACE is the space in the organization where your application is deployed. Spaces map to teams or products, hold applications, and have unique roles.
--sso Prompt for a one-time passcode to log in. SAP Single Sign-On is the safest and most recommended way to log in.

The org name, API endpoint, and space information can be found in the SAP BTP Cockpit under Home → Regions → Global Accounts → Subaccounts.

SAP BTP Cockpit Overview

Sample usage of the cf login command:

cf login -a https://api.cf.eu20.hana.ondemand.com -o myorg -s myspace --sso

API endpoint: https://api.cf.eu20.hana.ondemand.com



Temporary Authentication Code ( Get one at https://login.cf.eu20.hana.ondemand.com/passcode 😞

Upon executing the command with the --sso option, the Cloud Foundry CLI will display the API endpoint and prompt you for one-time passcode to log in.

Open a browser and navigate to the URL provided, such as https://login.cf.eu20.hana.ondemand.com/passcode
Authenticate yourself using SAP Single Sign-On.
SAP BTP SAP Single Sign-On
SAP BTP Temporary Authentication Code
Copy the one-time passcode generated.
Return to the console and paste the passcode into the prompt.
Once authenticated, the CLI will provide details about the targeted org and space.

Temporary Authentication Code ( Get one at https://login.cf.eu20.hana.ondemand.com/passcode 😞

Authenticating...

OK



Targeted org myorg.

Targeted space myspace.

API endpoint:   https://api.cf.eu20.hana.ondemand.com

API version:    3.99.0

user:           myemail@sap.com

org:            myorg

space:          myspace

Note that Cloud Foundry uses a role-based access control system to grant permissions to members, so make sure you've assigned the appropriate role permissions, such as being an org auditor.

Step 3: Connect to a Cloud Foundry Application Instance Using SSH

In Cloud Foundry, you can SSH into application instances unless an org/space manager has prohibited SSH access. If you would like more detailed information, you can refer to the Enable and Disable SSH Access documentation.

To check if an application is accessible via SSH, you can use the following command:

cf ssh-enabled myapp

ssh support is enabled for app 'myapp'.

If the app isn't accessible via SSH, it can be enabled with the command `cf enable-ssh`.

cf enable-ssh myapp

Enabling ssh support for app myapp as youremail@sap.com...

...

OK

You must restart your app after enabling SSH access. To restart your app, run the following command:

cf restart myapp

Please note that if a space manager has disabled SSH access at the space level, all applications within that space will inherit the access level. In such cases, even if you, as a developer, enable SSH access at the application level, you cannot SSH into individual applications.

Assuming SSH access is allowed at the deployment, space, and application level, you can initiate an interactive SSH session with the VM hosting the application by running the following command:

cf ssh myapp

Once connected, you will be in an interactive SSH session with the VM, indicated by the prompt:

vcap@afa9bea3-b619-6476-5e97-1328:~$

Step 4: Enable the Node.js Inspector for Remote Debugging on a Running Application Instance

To enable debug mode for a running Node.js process, you'll need to determine its unique process ID (PID). On Linux and Unix-like environments, you can use the ps command to obtain this information. Here's an example:

vcap@afa9bea3-b619-6476-5e97-1328:~$ ps aux



USER    PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND

vcap    151  0.0  0.1 687580 118376 ?       Sl   May28   0:05 node /home/vcap/deps/0/bin/npx cds run

...

Once the PID of the Node.js process running the application is known, you can use the kill command to send a debugging signal to it. The Node.js runtime activates the inspector protocol when it receives a usr1 signal. The inspector protocol is essentially a debugging protocol that allows tools to instrument, inspect, debug, and profile.

vcap@afa9bea3-b619-6476-5e97-1328:~$ kill -usr1 151

After sending this signal to the Node.js process, inspect the application logs. You should see that a debugger is now listening on ws://127.0.0.1:9229/48d7a94b-acb8-4d43-9932-95b781ee932d. This indicates that the Node.js process has switched to debug mode and is actively listening for debugging requests on a WebSocket server located at host and port 127.0.0.1:9229.

SAP BTP Cockpit Application Logs

Step 5: Enable Port Forwarding to Cloud Foundry

When using the cf ssh command

the -L flag enables local port forwarding, binding an output port on your machine to an input port on the application VM. Pass in a local port and your application VM port and port number, all colon-delimited. You can prepend your local network interface or use the default localhost.

Enables local port forwarding

$ cf ssh MY-APP -L [LOCAL-NETWORK-INTERFACE:]LOCAL-PORT:REMOTE-HOST-NAME:REMOTE-HOST-PORT

Here's an example of enabling local port forwarding using the `cf ssh` command:

cf ssh -N -L 9229:127.0.0.1:9229 myapp

This command initiates an SSH tunnel session where a connection to port 9229 on your development environment is forwarded to the myapp instance on port 9229.

Now, you can attach a debugger such as Visual Studio Code, SAP Business Application Studio (BAS), or Chrome DevTools to localhost:9229. With this setup, you'll be able to debug your application instance running on SAP BTP, Cloud Foundry environment as if the Node.js application were running locally.

Step 6: Attach a Node.js Debugger to a Process Running on a Cloud Foundry Application Instance

Node.js debuggers support attaching to a running program in debug mode. VS Code and Chrome DevTools have a built-in "Attach to Node Process" debugging model.

Here's how you can attach the debugger to a process running on a Cloud Foundry application instance:

Attach VS Code Debugger

Add the following debug configuration to your launch.json file:

{
    "configurations": [{
        "name": "Attach to a Cloud Foundry Instance on Port 9229",
        "port": 9229,
        "request": "attach",
        "type": "node",
        "localRoot": "${workspaceFolder}",
        "remoteRoot": "/home/vcap/app"
    }]
}

For example:

VS Code Debug Configuration

For detailed information on how to add a new debug configuration, refer to Add a new configuration

.

Launch VS Code and click on the Run and Debug button in the sidebar.

Click on Start Debugging to initiate the debugging session.

Open the Debug Console.

VS Code Debugger Console, Loaded Scripts ...

If you followed the previous steps, you should be able to interact with the REPL, view loaded scripts, and set breakpoints at this point.

Attach Chrome DevTools

Open the Chrome browser (or any Chromium-based browser) and enter chrome://inspect in the address bar. If you're using Microsoft Edge, it also supports the V8 JavaScript engine and can be used for debugging.

Chrome Browser Window

After navigating to the URL, you'll see the following page:

Chrome Browser Window (Inspect Devices)

On the Devices screen, click the Open dedicated DevTools for Node link. This will open a new window pops up for debugging a node session.

Chrome DevTools Node.js Debugger

Chrome Debugger Console Panel

If you followed the previous steps, we can now debug, interact with the REPL, source code, and set breakpoints.

Chrome Debugger Sources Panel

Conclusions

Following the steps outlined in this blog post, you can set up remote debugging for CAP Applications (Node.js Stack) at runtime on SAP BTP and Cloud Foundry Environment. This will allow you to diagnose and troubleshoot any issues that may arise in your applications. This approach will help you quickly identify the source of the problem and help you resolve it. Remote debugging provides a way to pinpoint the issue's exact location and can help developers effectively fix it.

CLOUD FOUNDRY, the CLOUD FOUNDRY logo, and other CLOUD FOUNDRY marks used in this block post are trademarks of the CloudFoundry.org Foundation in the United States and other countries.