📜 @saptools/cf-logs

Turn SAP BTP Cloud Foundry logs into a reusable engine, not a one-off UI feature.

Fetch snapshots, stream live output, normalize plain-text and JSON rows, emit compact high-signal context, and persist bounded log state to disk through one CLI and one typed Node.js API.

Install • Quick Start • CLI • Store • Security

✨ Features

• 📥 Recent snapshots — run cf logs --recent, normalize the result, and optionally persist it
• 📡 Live streams — wrap cf logs <app> with batching, reconnection, bounded in-memory state, and typed events
• 🧠 Log normalization — handle plain text, JSON logs, multiline continuations, and router access metadata such as method, request, status, latency, tenant, client IP, and separate correlation & hop request IDs
• 🪶 Compact output — project logs into concise rows with optional refs back to full saved rows
• 🗃️ Bounded local store — write snapshots to ~/.saptools/cf-logs-store.json with atomic file updates and locking
• 🧩 CLI and typed API — use the package from shell scripts, VSCode extensions, Node services, or test runners
• 🧪 Fake-backed E2E coverage — snapshot and stream flows are verified without live SAP access

📦 Install

# Global CLI
npm install -g @saptools/cf-logs

# Or as a dependency
npm install @saptools/cf-logs
# pnpm add @saptools/cf-logs
# yarn add @saptools/cf-logs

[!NOTE] Requires Node.js >= 20 and the official cf CLI on PATH.

Updates

Every command first checks npm for a newer @saptools/cf-logs (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:

cf-logs: updating 0.7.0 -> 0.8.0 ...
cf-logs: updated to 0.8.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-logs self-update forces the check and install now; cf-logs 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_LOGS_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

# 1. Export credentials used for cf api/auth
export SAP_EMAIL="[email protected]"
export SAP_PASSWORD="credential-placeholder"

# 2. Fetch a structured snapshot
cf-logs snapshot \
  --region ap10 \
  --org sample-org \
  --space sample \
  --app demo-app \
  --json

# 3. Start a live stream as line-delimited JSON events
cf-logs stream \
  --region ap10 \
  --org sample-org \
  --space sample \
  --app demo-app \
  --json

# 4. Stream compact rows and keep refs for drill-down
cf-logs stream \
  --region ap10 \
  --org sample-org \
  --space sample \
  --app demo-app \
  --compact \
  --save

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

🧰 CLI

Shared targeting flags

Most commands use the same target shape:

| Flag | Description | | --- | --- | | --region <key> | CF region key such as ap10 | | --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 | | --email <value> | Override SAP_EMAIL | | --password <value> | Override SAP_PASSWORD |

--region or --api-endpoint is required. Credentials default to SAP_EMAIL and SAP_PASSWORD.

[!WARNING] Prefer the environment variables over --password <value>. Process arguments are visible to other users on the machine via tools like ps, so passing credentials inline can leak them. The --password flag is kept as an explicit override for one-off scripts only.

cf-logs snapshot

Fetch recent logs for one app. By default the command prints bounded raw text. Use --json for structured rows, --compact for condensed output, and --save to persist. Cloud Foundry controls the --recent window; --since, --search, and --min-level filter rows after those logs are returned.

cf-logs snapshot \
  --region ap10 \
  --org sample-org \
  --space sample \
  --app demo-app \
  --json \
  --save

| Flag | Description | | --- | --- | | --json | Emit a full JSON snapshot object | | --compact | Emit compact rows instead of raw text or a full snapshot | | --compact-message-limit <count> | Maximum characters per compact message/body (default: 500) | | --compact-ttl-minutes <count> | Minutes before compact drill-down refs expire (default: 60) | | --save | Persist to the local store; with --compact, create temporary full-row refs instead | | --since <duration> | Filter rows after CF returns recent logs; accepts 15m, 45m, 1h, or 1d | | --search <text> | Keep rows matching text case-insensitively | | --min-level <level> | Keep rows at or above trace, debug, info, warn, error, or fatal | | --log-limit <count> | Maximum parsed rows and bounded raw-text budget |

cf-logs stream

Start a live log stream for one app. In JSON mode the command emits line-delimited events:

• {"type":"state",...}
• {"type":"lines",...}

cf-logs stream \
  --region ap10 \
  --org sample-org \
  --space sample \
  --app demo-app \
  --json

Useful stream options:

| Flag | Description | | --- | --- | | --json | Emit line-delimited JSON events | | --compact | Emit compact parsed rows instead of raw CF lines | | --compact-message-limit <count> | Maximum characters per compact message/body (default: 500) | | --compact-ttl-minutes <count> | Minutes before compact drill-down refs expire (default: 60) | | --save | Persist to the local store; with --compact, create temporary full-row refs instead | | --max-lines <count> | Stop after emitting N streamed lines | | --search <text> | Keep rows matching text case-insensitively | | --min-level <level> | Keep rows at or above trace, debug, info, warn, error, or fatal | | --log-limit <count> | Maximum parsed rows and bounded raw-text budget | | --flush-interval-ms <ms> | Batch window before append events are emitted | | --retry-initial-ms <ms> | Initial reconnect delay after unexpected stream exits | | --retry-max-ms <ms> | Maximum reconnect delay |

cf-logs show

Retrieve a full saved compact row by ref. Refs are emitted only when --compact --save is used.

cf-logs show 7f3a9c2b:42
cf-logs show 7f3a9c2b:42 --json

cf-logs session

Inspect or clear temporary compact drill-down sessions. Sessions expire after 60 minutes by default.

cf-logs session list
cf-logs session list --json
cf-logs session prune
cf-logs session clear

cf-logs apps

List started apps with running instances for one org/space.

cf-logs apps --region ap10 --org sample-org --space sample --json

cf-logs store path

Print the package-managed log store path.

cf-logs store path

cf-logs store list

Inspect cached store entries.

cf-logs store list
cf-logs store list --json

cf-logs store clear

Remove every cached entry from the package-managed log store. The store file remains in place but is rewritten with an empty entries list.

cf-logs store clear

cf-logs --version

Print the installed @saptools/cf-logs semantic version.

cf-logs --version

🔗 Request Identifiers

A parsed row exposes three identifier fields. They are not interchangeable, and picking the wrong one is the difference between finding a request and finding a few hundred.

| Field | Source | Grain | | --- | --- | --- | | correlationId | x_correlationid on a router line; correlation_id, x_correlation_id or x_correlationid in a JSON payload | One business transaction — constant across every hop | | vcapRequestId | vcap_request_id on a router line; x_vcap_request_id or request_id in a JSON payload | One HTTP hop — a fresh value per request | | requestId | router lines only — whichever of the two that line carried, correlation first | Legacy single slot, unchanged since 0.7.0 |

requestId predates the split and is kept byte-for-byte so existing callers keep working. It cannot tell you which identifier it holds, which is why the two typed fields exist.

One wrinkle worth knowing: on a JSON application row requestId is always empty — it has only ever been populated from router lines. The compact projection still fills its own requestId slot from the payload, exactly as it did in 0.7.0. correlationId and vcapRequestId are populated on both row kinds, which is the point of having them.

Joining a log row to an OpenTelemetry trace

vcapRequestId is the field to join on. Measured against a live tenant over 1,504 server spans, it resolved to exactly one trace every time; within that same sample correlationId averaged 13.29 traces per value and reached 777, and over a full retention window a single value has been measured covering 6,796 traces — because it identifies the whole transaction rather than one request.

The matching span attribute is span.attributes.http@request@header@x-vcap-request-id:

# 1. read the hop id off the log row (compact keeps it, so no full snapshot needed)
cf-logs snapshot --app demo-app --compact --json | jq -r '.rows[] | select(.vcapRequestId) | .vcapRequestId'

# 2. resolve it to a trace, then analyze that trace
cf-otel find --vcap-request-id <id>
cf-otel selftime <traceId>

[!NOTE] Spans reach the trace index a few seconds after the log line, so a lookup run immediately can report no rows for a trace that exists. Needs @saptools/cf-otel 0.7.0 or newer. On older versions the flag does not exist and = does not match this field, because the attribute is stored as a JSON array rendered to text (["<id>"]) — use --service <app> --attr 'http@request@header@x-vcap-request-id~<id>' there.

In compact output vcapRequestId is printed whenever the row has one, even when it repeats requestId. Suppressing the duplicate saved a few characters but made two rows carrying different kinds of identifier print identically, which defeats the point of joining on it. requestId itself is byte-for-byte what 0.7.0 emitted.

📁 Store File

The package-managed store lives here:

~/.saptools/cf-logs-store.json

It contains bounded full-fidelity entries keyed by:

• apiEndpoint
• org
• space
• app

Each entry stores:

• rawText
• fetchedAt
• updatedAt
• rowCount
• truncated

The store is an implementation detail. Prefer readStore(), persistSnapshot(), cf-logs store path, or cf-logs store list over parsing the file directly.

🔐 Data Notes

• The CLI and runtime do not redact log content.
• Persisted snapshots are bounded and written with file locking plus atomic replace semantics.
• Store and session files can contain credentials, tokens, personal data, or business data if the application logs them.
• The store file and compact session files are not safe for public repositories.
• Compact mode reduces token volume only; it is not a privacy feature.
• Temporary compact sessions live under ~/.saptools/cf-logs-sessions/ and are pruned after their TTL.

❓ FAQ

No. The package is intentionally UI-agnostic. It exposes a CLI, a runtime engine, normalization helpers, and store helpers that can be used by VSCode, terminal tools, tests, or backend processes.

Because log normalization, streaming, compact projection, and store management are reusable engine concerns. Keeping them in a package makes the IDE layer smaller, easier to test, and easier to evolve.

No. Persistence is opt-in. Use --save in the CLI or enable persistSnapshots / persistStreamAppends in CfLogsRuntime.

Yes. Pass --api-endpoint <url> in the CLI or apiEndpoint in the Node.js API.

🛠️ Development

From the monorepo root:

pnpm install
pnpm --filter @saptools/cf-logs cspell
pnpm --filter @saptools/cf-logs lint
pnpm --filter @saptools/cf-logs typecheck
pnpm --filter @saptools/cf-logs test:unit
pnpm --filter @saptools/cf-logs test:e2e
pnpm --filter @saptools/cf-logs build
pnpm --filter @saptools/cf-logs check

🤝 Author

Maintained by dongtran.