# @saptools/cf-live-trace

> Inject a runtime HTTP trace hook into SAP BTP Cloud Foundry Node.js apps and stream request/response events from the CLI.

Latest version **0.3.1** (published 2026-09-02) · MIT license · 693 weekly downloads

## Install

```sh
npm install @saptools/cf-live-trace
pnpm add @saptools/cf-live-trace
yarn add @saptools/cf-live-trace
bun add @saptools/cf-live-trace
```

Provides the command `cf-live-trace`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; growing popularity.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.1 |
| Published | 2026-09-02 |
| First published | 2026-06-25 |
| Weekly downloads | 693 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 2 |
| Unpacked size | 681 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | Dong Tran |
| Maintainers | dongtran |
| Keywords | sap, cloud-foundry, btp, trace, http, request, response, node-inspector, cli, saptools |

## Links

- npm: https://www.npmjs.com/package/@saptools/cf-live-trace
- Repository: https://github.com/dongitran/saptools
- Homepage: https://github.com/dongitran/saptools/tree/main/packages/cf-live-trace#readme
- Issues: https://github.com/dongitran/saptools/issues
- npm.io page: https://npm.io/package/@saptools/cf-live-trace

## Dependencies (2)

- [commander](https://npm.io/package/commander.md) ^13.0.0
- [@saptools/cf-inspector](https://npm.io/package/@saptools/cf-inspector.md) ^0.4.8 || ^0.5.0 || ^0.8.0 || ^0.9.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 0.3.1 (latest) — 2026-09-02
- 0.3.0 — 2026-09-02
- 0.2.1 — 2026-07-16
- 0.2.0 — 2026-07-01
- 0.1.9 — 2026-06-30
- 0.1.8 — 2026-06-30
- 0.1.6 — 2026-06-29
- 0.1.5 — 2026-06-29
- 0.1.4 — 2026-06-26
- 0.1.3 — 2026-06-26
- 0.1.2 — 2026-06-26
- 0.1.1 — 2026-06-25
- 0.1.0 — 2026-06-25

## README

<div align="center">

# `@saptools/cf-live-trace`

**Inject a bounded HTTP trace hook into a running SAP BTP Cloud Foundry Node.js app and stream request/response events from the CLI.**

[![npm version](https://img.shields.io/npm/v/@saptools/cf-live-trace.svg?style=flat&color=CB3837&logo=npm)](https://www.npmjs.com/package/@saptools/cf-live-trace)
[![license](https://img.shields.io/npm/l/@saptools/cf-live-trace.svg?style=flat&color=blue)](./LICENSE)
[![node](https://img.shields.io/node/v/@saptools/cf-live-trace.svg?style=flat&color=339933&logo=node.js&logoColor=white)](https://nodejs.org)
[![types](https://img.shields.io/npm/types/@saptools/cf-live-trace.svg?style=flat&color=3178C6&logo=typescript&logoColor=white)](https://www.typescriptlang.org)

[Install](#install) - [Quick Start](#quick-start) - [CLI](#cli) - [Security](#security-notes)

</div>

---

## Features

- Runtime HTTP tracing for Node.js apps already running on Cloud Foundry.
- Automatic CF session setup, SSH enablement check, Node inspector startup, and SSH port forwarding.
- CDP-based JavaScript injection derived from the SAP Tools VS Code Live Trace flow.
- Request and response header capture, bounded body capture, status, duration, byte counts, correlation id, and bounded queue drops.
- Compact stdout for scripts and agents: headers and app id stay out of live output, common credential query values are redacted, body previews are capped at 128 characters, and full captured events are saved locally.
- Per-request backup JSON files under `~/.saptools/cf-live-trace/sessions/` with two-hour retention and session inspection commands for large JSON bodies.
- Strict TypeScript, ESLint, unit coverage, and fake-backed E2E tests without live SAP access.

---

## Install

```bash
npm install -g @saptools/cf-live-trace

# or as a library
npm install @saptools/cf-live-trace
```

Requires Node.js >= 20 and the official `cf` CLI on `PATH`.

The target Cloud Foundry app must be a Node.js process where `cf ssh` can reach `127.0.0.1:9229` after Node inspector startup. If SSH is disabled, the CLI enables SSH and restarts the app before opening the tunnel.

---

## Updates

Every command first checks npm for a newer `@saptools/cf-live-trace` (at most once an hour, one small request
with a 2-second timeout) and, when one exists, installs that exact version with the package manager
that owns the running binary and re-runs the command you typed on the new version. Both steps are
announced on stderr; nothing is printed when the install is already current:

```text
cf-live-trace: updating 0.3.0 -> 0.4.0 ...
cf-live-trace: updated to 0.4.0; re-running the command
```

If the install cannot complete, one stderr line gives the manual command and the command runs on the
installed version; that version is not retried for a day. `cf-live-trace self-update` forces the check and
install now; `cf-live-trace self-update --check` only reports.

| Control | Effect |
| --- | --- |
| `SAPTOOLS_AUTO_UPDATE=on\|notify\|off` | `on` (default) installs and re-runs; `notify` prints the manual command once per version; `off` never checks. Applies to every `@saptools` CLI. |
| `CF_LIVE_TRACE_AUTO_UPDATE` | same values, this CLI only; wins over the global variable |
| `SAPTOOLS_UPDATE_INTERVAL_MINUTES` | minutes between checks (default `60`; `0` checks on every run) |
| `SAPTOOLS_NPM_REGISTRY` | registry to check and install from (default: npm's configured registry, then npmjs) |
| `SAPTOOLS_UPDATE_DEBUG=1` | explain on stderr why nothing happened |

The updater switches itself off in CI (`CI` set), under `NODE_ENV=test` or `NO_UPDATE_NOTIFIER`, when
the binary runs from a source checkout, an `npm link` or an `npx` cache, and inside the re-run itself.
It never writes to stdout, never asks for input, never uses `sudo`, and never moves onto a prerelease.
Its state lives in `~/.saptools/updates/`.

## Quick Start

```bash
export SAP_EMAIL="sample@example.com"
export SAP_PASSWORD="<password>"

cf-live-trace \
  --region ap10 \
  --org sample-org \
  --space dev \
  --app orders-api \
  --instance 0 \
  --format ndjson
```

If you already know the CF API endpoint, replace `--region ap10` with `--api-endpoint https://api.cf.ap10.hana.ondemand.com`.

By default the command streams one JSON object per captured HTTP request and runs until `Ctrl+C`.

```json
{"id":"1","sessionId":"s1a2b3c4d5e6f7a8b","requestId":"r1a2b3c4d5e6f7a8","method":"POST","normalizedUrl":"/orders","status":201,"durationMs":24,"requestBodyFormat":"json","responseBodyFormat":"json"}
```

---

## CLI

```bash
cf-live-trace --help
```

Targeting flags:

| Flag | Description |
| --- | --- |
| `--region <key>` | CF region key (defaults via `cf target` when omitted; errors if no current target when only app given) |
| `--api-endpoint <url>` | Explicit CF API endpoint instead of a region key |
| `--org <name>` | CF org name |
| `--space <name>` | CF space name |
| `--app <name>` | CF app name |
| `--instance <index>` | CF app instance index, default `0` |
| `--email <value>` | Override `SAP_EMAIL` |
| `--password <value>` | Override `SAP_PASSWORD` |
| `--cf-home <dir>` | Reuse an existing CF home instead of a temporary one |
| `--cf-command <path>` | CF CLI executable or test shim |

Trace flags:

| Flag | Description |
| --- | --- |
| `--duration <seconds>` | Stop after N seconds |
| `--max-events <count>` | Stop after N captured trace events |
| `--max-body-bytes <bytes>` | Maximum request/response capture bytes, default `4096`; must be greater than `0` |
| `--no-capture-headers` | Do not capture request/response headers |
| `--no-capture-request-body` | Do not capture request body previews |
| `--no-capture-response-body` | Do not capture response body previews |
| `--no-uninstall-on-exit` | Disable the injected hook instead of uninstalling it |
| `--format <format>` | `ndjson`, `summary`, or `json` |
| `--quiet` | Suppress progress lines on stderr |

Prefer `SAP_EMAIL` and `SAP_PASSWORD` over inline credential flags. Process arguments can be visible to other users on the same machine.

Each captured request is also saved as a private JSON file under:

```text
~/.saptools/cf-live-trace/sessions/<sessionId>/events/
```

Files expire after two hours. Expired files are pruned while tracing and when session commands run. The path is based on Node's user home directory, so Windows uses the current user's profile directory.

---

## Examples

Stop after the first five requests and print a compact text stream:

```bash
cf-live-trace \
  --api-endpoint https://api.cf.ap10.hana.ondemand.com \
  --org sample-org \
  --space dev \
  --app orders-api \
  --max-events 5 \
  --format summary
```

Capture headers only, without body previews:

```bash
cf-live-trace \
  --region ap10 \
  --org sample-org \
  --space dev \
  --app orders-api \
  --no-capture-request-body \
  --no-capture-response-body
```

Emit one final JSON document for downstream processing:

```bash
cf-live-trace \
  --region ap10 \
  --org sample-org \
  --space dev \
  --app orders-api \
  --duration 30 \
  --format json
```

Inspect, export, or replay a saved session after or during a trace run:

```bash
cf-live-trace session events s1a2b3c4d5e6f7a8b --method POST --limit 20
cf-live-trace session search s1a2b3c4d5e6f7a8b orderId --body response --length 256
cf-live-trace session body s1a2b3c4d5e6f7a8b r1a2b3c4d5e6f7a8 --body response --path /data/items/0 --limit 4000 --rows 100
cf-live-trace session curl s1a2b3c4d5e6f7a8b r1a2b3c4d5e6f7a8 --target http://localhost:4004 --out replay.sh
cf-live-trace session replay s1a2b3c4d5e6f7a8b r1a2b3c4d5e6f7a8 --target http://localhost:4004
cf-live-trace session prune
```

`session curl` reconstructs an absolute URL from `x-forwarded-proto`, `x-forwarded-host`, or `host` when `--target` is omitted. Without `--copy` or `--out`, it truncates displayed header values and request bodies to keep terminals responsive; use `--copy` or `--out` for the full command. Both `session curl` and `session replay` refuse to run when the captured request body was already truncated by `--max-body-bytes`, because replaying an incomplete payload is usually misleading. Hop-by-hop headers such as `host` and `content-length` are omitted from generated and replayed requests so the target HTTP client can recalculate them safely.

---

## How It Works

`cf-live-trace` follows the same high-level route as the SAP Tools VS Code Live Trace feature:

1. Prepare an isolated CF session with `cf api`, `cf auth`, and `cf target`.
2. Ensure SSH is enabled for the app.
3. Run a robust `/proc` scan inside the app container and send `SIGUSR1` to the best Node.js process candidate.
4. Open `cf ssh -L <local>:127.0.0.1:9229` for the selected app instance.
5. Attach to the Node inspector over CDP using `@saptools/cf-inspector`.
6. Evaluate a runtime hook that patches Node's `http` and `https` server prototypes.
7. Poll a bounded in-process queue with acknowledgement-based retries, save each drained trace event locally, and stream compact trace events back to stdout.
8. Disable or uninstall the hook and close the tunnel on exit.

The injected global is named `__SAPTOOLS_CF_LIVE_TRACE__` so CLI sessions do not collide with the VS Code extension's Live Trace runtime global.

---

## Security Notes

- This tool injects JavaScript into a running Node.js process through the Node inspector. Use it only for apps and spaces you are authorized to inspect.
- Captured headers and bodies can contain credentials, tokens, cookies, or personal data. Backup files are private by default, but keep the user profile and CI artifacts protected.
- Live stdout intentionally omits request/response headers and app id, redacts common credential query values, and only prints 128 characters of each captured body. Backup JSON files retain the fuller captured event for two hours.
- `--max-body-bytes` bounds captured body data transported back from the app and must be greater than zero. Set it lower for sensitive or high-throughput services.
- The CLI avoids putting credentials in `cf auth` arguments; credentials are passed to the CF CLI through `CF_USERNAME` and `CF_PASSWORD`.
- If cleanup fails, the runtime hook can remain disabled or installed until the app process restarts. Progress events report this state.

---

## Development

```bash
pnpm install
pnpm --filter @saptools/cf-live-trace build
pnpm --filter @saptools/cf-live-trace lint
pnpm --filter @saptools/cf-live-trace typecheck
pnpm --filter @saptools/cf-live-trace test:unit
pnpm --filter @saptools/cf-live-trace test:e2e
```

The E2E test starts a local inspectable Node.js app and a fake `cf` executable that opens a real TCP proxy to the app inspector. No live SAP account is required.

---
_Source: https://npm.io/package/@saptools/cf-live-trace · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._