From 5b2d96c177beff0775232f11c7b2c911fbd8845c Mon Sep 17 00:00:00 2001 From: Christian Georgi Date: Fri, 17 Jan 2025 17:38:01 +0100 Subject: [PATCH] `cds debug` for Java --- tools/cds-cli.md | 87 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 78 insertions(+), 9 deletions(-) diff --git a/tools/cds-cli.md b/tools/cds-cli.md index 83a35b322..db556031b 100644 --- a/tools/cds-cli.md +++ b/tools/cds-cli.md @@ -546,17 +546,41 @@ There a couple of shortcuts and convenience functions: ::: -## Debugging with `cds debug` {.nodejs} +## Debugging with `cds debug` {#cds-debug} -`cds debug` lets you debug Node.js applications in Chrome DevTools running locally or in Cloud Foundry. +`cds debug` lets you debug applications running locally or remotely on Cloud Foundry. +Local applications will be started in debug mode, while (already running) remote applications are put into debug mode. -To debug remote applications in the currently targeted CF space, run: +To debug a application on Cloud Foundry, make sure +- to be logged in to the space where the application is deployed to, +- that you have developer permissions in the space +- that the app is running and [reachable through SSH](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html#check-ssh-permissions). + +Effectively, run: +```sh +cf login # select the correct org and space here +cf ssh-enabled # to check if SSH is enabled +``` + +::: tip Scale to one application instance only +We recommend to only scale to _one_ app instance on SAP BTP Cloud Foundry, as then your request is guaranteed to hit this one instance. +If you scale out to more instances, only some of your requests will hit the instance that the debugger is connected to. This can result in 'missed breakpoints'. + +However, it's possible to [route a request to a specific instance](https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html#surgical-routing), which is useful if you can't reduce the number of app instances. +::: + + +### Node.js Applications + +To debug remote Node.js applications in the currently targeted CF space, run: 
-$ cds debug bookshop-srv
+$ cds debug <app-name>
 
-Opening SSH tunnel for CF app 'bookshop-srv'
+Opening SSH tunnel on 9229:127.0.0.1:9229
 Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=...
+
+> Keep this terminal open while debugging.
This opens an [SSH tunnel](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html), puts the application in debug mode, and connects and opens the [debugger of Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript). @@ -575,13 +599,58 @@ Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=... [cds] - ... -::: tip Scale to one application instance only -We recommend to only scale to _one_ app instance on SAP BTP Cloud Foundry, as then your request is guaranteed to hit this one instance. -If you scale out to more instances, only some of your requests will hit the instance that the debugger is connected to. This can result in 'missed breakpoints'. +::: details Under the hoods, these commands are executed: +```sh +cf ssh -c "kill -usr1 `pidof node`" +cf ssh -N -L 9229:localhost:9229 +``` +::: -However, it's possible to [route a request to a specific instance](https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html#surgical-routing), which is useful if you can't reduce the number of app instances. +### Java Applications + +To debug remote Java applications in the currently targeted CF space, run: + +
+$ cds debug <app-name>
+...
+Debugging has been started.
+Address : 8000
+
+Opening SSH tunnel on 8000:127.0.0.1:8000
+
+> Keep this terminal open while debugging.
+
+ +This opens an [SSH tunnel](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html) and puts the application in debug mode. + +::: details Under the hoods, these commands are executed: +```sh +cf ssh -c "~/app/META-INF/.sap_java_buildpack/sap_machine_jre/bin/jcmd `pidof java` VM.start_java_debugging" +cf ssh -N -L 8000:localhost:8000 +``` +::: + +Afterwards, you need to connect a debugger from your IDE to it at the given port. In VS Code, for example, add a launch configuration like this one: + +::: code-group +```json [.vscode/launch.json] +{ + "type": "java", + "name": "Attach to Remote Java App", + "request": "attach", + "hostName": "localhost", + "port": "8000" +} +``` ::: +Make sure the port matches to what the debug tunnel uses (see the message in the terminal). The default port is `8000`. + +> [!NOTE] SapMachine is required +> SapMachine is required as Java runtime environment for this feature to work.
+> There is nothing to do if you set up your MTA deployment descriptors with [`cds mta`](../guides/deployment/to-cf#add-mta-yaml) or CAP project wizards. +> See the [documentation of SapMachine](https://help.sap.com/docs/btp/sap-business-technology-platform/sapmachine) for how to configure this manually. + ## Debugging with `cds watch`