simplemdg-dev-cli 1.4.1 → 2.0.4

package/README.md

@@ -281,3 +281,116 @@ Do not commit real secrets to Git.
 Files like `.npmrc`, `default-env.json`, and cached passwords may contain sensitive data.
 
 Use saved password only on your own machine.
+
+
+## Request Trace
+
+```bash
+smdg cf request-trace
+```
+
+Watch incoming HTTP requests on deployed BTP Node.js/CAP apps without editing backend source code.
+
+The CLI guides you to select one or more apps, choose trace depth, prepare Node Inspector, inject a temporary runtime trace, and stream request logs.
+
+It can show method, path, headers, request body, response body, status, and duration. Authorization tokens are masked by default and should only be shown fully in dev/test environments.
+
+Alias:
+
+```bash
+smdg cf traffic
+```
+
+Notes:
+
+- This works best for Node.js/CAP apps.
+- It uses CF SSH tunnel and Node Inspector.
+- It does not change repository source code.
+- The trace disappears after app restart.
+- Avoid full token/body tracing in production.
+
+## New in 2.0.2: HTTP Watch
+
+`request-trace` deep runtime injection is experimental and may not catch every CAP runtime request body. Version 2.0.2 adds a stable log-based watcher:
+
+```bash
+smdg cf http-watch
+```
+
+It reads existing CF/CDS/RTR logs and prints a clean realtime HTTP view: method, path, status, user, tenant, instance, request size, and request id. It does not restart apps and does not change source code.
+
+Use this first for reliable microservice tracking. For deeper diagnostics:
+
+```bash
+smdg cf request-trace-doctor
+```
+
+`request-trace` now asks which engine to use: stable HTTP watch, experimental deep inspector trace, or doctor.
+
+## Network body capture
+
+Use this when `smdg cf http-watch` can show POST/PATCH requests but not the request body.
+
+```bash
+smdg cf request-trace
+```
+
+Choose **Deep Node Inspector trace**. The CLI injects a temporary Node runtime hook through the Node Inspector. It does not modify repository source code. It attempts to capture request headers, body, response status, and response body depending on the selected mode.
+
+Recommended test flow:
+
+1. Run `smdg cf request-trace`.
+2. Select the target app.
+3. Select **Deep Node Inspector trace**.
+4. Select **Headers + body**.
+5. Select **Mask token** first.
+6. If the inspector is not reachable, choose the prepare mode that sets `NODE_OPTIONS` and restarts the app.
+7. Send a new request after the CLI prints that the trace is installed.
+
+Important: full body/token capture is a dev/test feature only. Do not enable full token output in production.
+
+
+# Request Trace Runtime Tools
+
+Use this command when you need to inspect real request headers and bodies from a BTP Node.js/CAP app without changing repository source code:
+
+```bash
+smdg cf request-trace
+```
+
+Alias:
+
+```bash
+smdg cf network-trace
+```
+
+The CLI will ask for:
+
+* target app or apps
+* trace depth: path, headers, body, or response body
+* Authorization handling: masked, full, or omitted
+* displayed headers: minimal, common, all, or custom
+* whether to parse body as JSON/form data
+* whether to export trace events to a JSONL file
+
+While the trace is running, you can type commands directly in the same terminal:
+
+```txt
+/method POST
+/path getBusinessRequest
+/body CR0000135951
+/status 500
+/text single.npi
+/headers authorization,content-type,x-correlationid,x-vcap-request-id
+/headers all
+/clear
+/show
+/replay
+/pause
+/resume
+/help
+```
+
+Exported files use JSONL format: one request event per line. This makes it easier to search later with editor tools or scripts.
+
+Security note: full Authorization token output should only be used in dev/test and on a trusted machine. The recommended mode is masked token.

package/USER_GUIDE.md

@@ -281,3 +281,132 @@ Do not commit real secrets to Git.
 Files like `.npmrc`, `default-env.json`, and cached passwords may contain sensitive data.
 
 Use saved password only on your own machine.
+
+
+## Request Trace
+
+```bash
+smdg cf request-trace
+```
+
+Watch incoming HTTP requests on deployed BTP Node.js/CAP apps without editing backend source code.
+
+The CLI guides you to select one or more apps, choose trace depth, prepare Node Inspector, inject a temporary runtime trace, and stream request logs.
+
+It can show method, path, headers, request body, response body, status, and duration. Authorization tokens are masked by default and should only be shown fully in dev/test environments.
+
+Alias:
+
+```bash
+smdg cf traffic
+```
+
+Notes:
+
+- This works best for Node.js/CAP apps.
+- It uses CF SSH tunnel and Node Inspector.
+- It does not change repository source code.
+- The trace disappears after app restart.
+- Avoid full token/body tracing in production.
+
+# HTTP Watch
+
+Use this when you want to see what is calling your BTP app without adding backend logs.
+
+```bash
+smdg cf http-watch
+```
+
+The CLI shows a clean realtime list from existing Cloud Foundry/CDS/router logs.
+
+It can show:
+
+* HTTP method
+* URL/path
+* status code
+* duration
+* app instance
+* remote user
+* tenant
+* request size
+* request id / correlation id
+
+It cannot show full body or full Authorization token because CF/CDS logs do not contain them. Use `smdg cf request-trace` only when you need experimental deep runtime inspection.
+
+# Request Trace Doctor
+
+Use this before trying deep body capture:
+
+```bash
+smdg cf request-trace-doctor
+```
+
+It checks recent router/app traffic and the remote Node process list so you can confirm whether the app is receiving requests and whether deep inspection is possible.
+
+# Network Trace
+
+```bash
+smdg cf request-trace
+```
+
+This command can capture request data from inside a running Node.js/CAP app.
+
+Use it when you need more than `smdg cf http-watch`, especially request body for POST/PATCH APIs.
+
+Recommended mode:
+
+```txt
+Deep Node Inspector trace
+Headers + body
+Mask token
+```
+
+The trace is temporary and disappears after the app restarts. It does not change source code.
+
+If the CLI cannot reach the Node inspector, run the command again and choose the prepare option that sets `NODE_OPTIONS` and restarts the app.
+
+
+# Request Trace Runtime Tools
+
+Use this command when you need to inspect real request headers and bodies from a BTP Node.js/CAP app without changing repository source code:
+
+```bash
+smdg cf request-trace
+```
+
+Alias:
+
+```bash
+smdg cf network-trace
+```
+
+The CLI will ask for:
+
+* target app or apps
+* trace depth: path, headers, body, or response body
+* Authorization handling: masked, full, or omitted
+* displayed headers: minimal, common, all, or custom
+* whether to parse body as JSON/form data
+* whether to export trace events to a JSONL file
+
+While the trace is running, you can type commands directly in the same terminal:
+
+```txt
+/method POST
+/path getBusinessRequest
+/body CR0000135951
+/status 500
+/text single.npi
+/headers authorization,content-type,x-correlationid,x-vcap-request-id
+/headers all
+/clear
+/show
+/replay
+/pause
+/resume
+/help
+```
+
+Exported files use JSONL format: one request event per line. This makes it easier to search later with editor tools or scripts.
+
+Security note: full Authorization token output should only be used in dev/test and on a trusted machine. The recommended mode is masked token.