Stream heap dumps through hprof-redact

Author: parttimenerd

.github/workflows/build-and-snapshot.yml

@@ -231,9 +231,9 @@ jobs:
             ```sh
             # on Mac arm64
             cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-macos-arm64
-            # on Windows x86
+            # on Windows amd64
             cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-windows-amd64
-            # on Linux x86
+            # on Linux amd64
             cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-linux-amd64
             ```
 

.gitignore

@@ -26,7 +26,7 @@ _testmain.go
 # Tools
 counterfeiter
 
-# Built binaries
+# Build output directories
 build/
 pkg/
 
@@ -49,11 +49,54 @@ test/snapshots/
 # Heap dump files
 *.hprof
 
-# Build artifacts
+# Embedded/downloaded build artifacts
 dist
 
-# go
-pkg
+# Local project binaries
+requires
+
+# OS/editor/local tooling
+.DS_Store
+.claude/
+.playwright-mcp/
+.test_success_cache.json
+*.log
+*.tmp
+*.bak
+*~
+
+# Python local caches / coverage
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Local investigation / scratch artifacts
+BUG*.md
+FIX*.md
+*_REPORT.md
+*analysis*.py
+append_*.py
+discover*.py
+investigate*.py
+*_test_output.txt
+*_results.txt
+*.out
+out.zip
+
+# Local runtime artifacts
+sapmachine21-status/
+sapmachine21-status.zip
+sapmachine21-heapdump-*.hprof.gz
+sapmachine21-heapdump-*-redacted.hprof.gz
+
+# Local ad-hoc test helpers/artifacts
+test/doc_bugs_finder.py
+test/sapmachine21-status.zip
+test/test_bugs.py
+test_bugs.sh
+test_edge_cases.py
+test_fixes.py
 
 # Internal planning docs (superpowers skill artifacts)
 docs/superpowers/

.tool.yaml

@@ -2,7 +2,8 @@ tag: ready
 github_url: https://github.com/SAP/cf-cli-java-plugin
 tagline: Cloud Foundry CLI plugin to troubleshoot Java apps running on CF without SSH. Trigger heap
   dumps, thread dumps, and async-profiler or JFR recordings from the cf command line, with results
-  streamed back to your machine. Also embeds jstall for full JVM inspection via `cf java jstall`.
+  streamed back to your machine. Heap dumps can be redacted during download, kept compressed, or
+  opened directly in hprof-analyzer. Also embeds jstall for full JVM inspection via `cf java jstall`.
 tagline_short: Trigger heap dumps, thread dumps, and profiles from the CF CLI — no SSH needed.
 when_to_use:
 - You run Java apps on Cloud Foundry and need heap dumps, thread dumps, or CPU profiles
@@ -24,6 +25,7 @@ install:
     # Pick the binary for your platform:
     cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/latest/download/cf-cli-java-plugin-macos-arm64
     # linux-amd64 / linux-arm64 / windows-amd64 / windows-arm64 also available
+    # macOS requires Apple Silicon; macOS Intel (darwin/amd64) is not supported
 - label: CF Community
   lang: bash
   code: |
@@ -34,8 +36,19 @@ usage:
   lang: bash
   code: |
     cf java heap-dump my-app
+    cf java heap-dump my-app --redact --open
+    cf java heap-dump my-app --redact --compress
     cf java thread-dump my-app
     cf java jstall my-app
+features:
+- title: Stream heap dumps directly to your machine
+  body: Capture heap dumps and thread dumps from Cloud Foundry apps without manual SSH sessions.
+- title: Redact sensitive heap-dump data during download
+  body: Use `--redact` or `--redact-complete` to zero sensitive primitive data while the dump is being streamed, so an unredacted heap dump is never written locally.
+- title: Keep dumps compressed or open them immediately
+  body: Use `--compress` to save `.hprof.gz` files directly, or `--open` / `--open-url` to inspect the heap dump in hprof-analyzer right after download.
+- title: Run bundled jstall diagnostics
+  body: Inspect deadlocks, hot threads, flame graphs, and more via `cf java jstall` without separately installing jstall.
 how_to:
 - title: My CF app is not responding — find what it is stuck on
   body: |
@@ -201,6 +214,23 @@ how_to:
     ```
     The unredacted dump is never written to disk — redaction happens in-memory during download.
 
+- title: Capture a safer heap dump for sharing or browser analysis
+  body: |
+    If you need to inspect a heap dump locally or share it with others, combine redaction,
+    compression, and browser opening as needed:
+    ```bash
+    # Redact sensitive values and keep the dump compressed:
+    cf java heap-dump $APP_NAME --redact --compress
+
+    # Redact and open immediately in hprof-analyzer:
+    cf java heap-dump $APP_NAME --redact --open
+
+    # Use complete redaction for maximum privacy:
+    cf java heap-dump $APP_NAME --redact-complete --compress
+    ```
+    Use `--redact-keep-on-error` only if you explicitly want to keep a partially written redacted
+    file when local redaction fails.
+
 - title: Open a heap dump in hprof-analyzer
   body: |
     After downloading, the plugin can spin up a temporary local server and open

CHANGELOG.md

@@ -7,6 +7,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Changed
+
+- macOS plugin support now requires Apple Silicon. macOS Intel (`darwin/amd64`) is not supported.
+
 ### Added
 
 - Bundle [jstall](https://github.com/parttimenerd/jstall) (jstall-minimal.jar) for one-shot JVM inspection via

Makefile

@@ -38,7 +38,7 @@ endif
 # Downloaded at compile time from hprof-analyzer GitHub releases.
 # Uses musl-static Linux builds so the binary runs in CF containers without
 # glibc version constraints.
-HPROF_REDACT_BASE = https://github.com/parttimenerd/hprof-analyzer/releases/latest/download
+HPROF_REDACT_BASE = https://github.com/parttimenerd/hprof-analyzer/releases/download/nightly
 
 dist/hprof-redact-linux-amd64:
 	mkdir -p dist

README.md

@@ -15,11 +15,14 @@ Currently, it allows you to:
   ([SapMachine](https://sapmachine.io) only) profiles
 - Run [jstall](https://github.com/parttimenerd/jstall) for one-shot JVM inspection (deadlock detection, hot threads,
   dependency graphs, and more): bundled directly in the plugin, requires Java 17+ locally
-- Redact heap dumps before saving to remove sensitive data (`--redact`, `--redact-complete`)
+- Redact heap dumps before saving to remove sensitive data (`--redact`, `--redact-complete`) using the bundled
+  [`hprof-redact`](https://github.com/parttimenerd/hprof-analyzer) binary from the
+  [`hprof-analyzer`](https://github.com/parttimenerd/hprof-analyzer) project
 - Automatically compress heap dump transfers over SSH on JDK 17+ containers;
   use `--compress` to keep the local file as `.hprof.gz`
-- Open heap dumps directly in the [hprof-analyzer](https://parttimenerd.github.io/hprof-analyzer) web app
-  after downloading (`--open`)
+- Open heap dumps directly in the hosted
+  [`hprof-analyzer`](https://parttimenerd.github.io/hprof-analyzer) web app after downloading (`--open`) or point the
+  plugin at another `hprof-analyzer` instance via `--open-url`
 
 ## Installation
 
@@ -44,16 +47,18 @@ Download the latest release from [GitHub](https://github.com/SAP/cf-cli-java-plu
 To install a new version of the plugin, run the following:
 
 ```sh
-# on Mac arm64
+# on Mac arm64 (Apple Silicon only)
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/latest/download/cf-cli-java-plugin-macos-arm64
-# on Windows x64
+# on Windows amd64
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/latest/download/cf-cli-java-plugin-windows-amd64
-# on Linux x64
+# on Linux amd64
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/latest/download/cf-cli-java-plugin-linux-amd64
 # on Linux arm64
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/latest/download/cf-cli-java-plugin-linux-arm64
 ```
 
+macOS plugin binaries currently require Apple Silicon; macOS Intel (`darwin/amd64`) is not supported.
+
 You can verify that the plugin is successfully installed by looking for `java` in the output of `cf plugins`.
 
 ### Manual Installation of Snapshot Release
@@ -64,16 +69,18 @@ This is intended for experimentation and might fail.
 To install a new version of the plugin, run the following:
 
 ```sh
-# on Mac arm64
+# on Mac arm64 (Apple Silicon only)
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-macos-arm64
-# on Windows x64
+# on Windows amd64
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-windows-amd64
-# on Linux x64
+# on Linux amd64
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-linux-amd64
 # on Linux arm64
 cf install-plugin https://github.com/SAP/cf-cli-java-plugin/releases/download/snapshot/cf-cli-java-plugin-linux-arm64
 ```
 
+macOS snapshot binaries currently require Apple Silicon; macOS Intel (`darwin/amd64`) is not supported.
+
 ## Common Tasks
 
 ### My CF app is not responding — find what it is stuck on
@@ -224,10 +231,15 @@ cf java heap-dump $APP_NAME --open --redact --compress
 cf java heap-dump $APP_NAME --open-url http://localhost:8080
 ```
 
+The browser integration uses the [`hprof-analyzer`](https://github.com/parttimenerd/hprof-analyzer) project. By
+default, `--open` launches the hosted web app at <https://parttimenerd.github.io/hprof-analyzer>. Use `--open-url` if
+you run your own local or internal `hprof-analyzer` deployment.
+
 > **macOS note:** On macOS with the Application Firewall enabled, a dialog will appear asking
 > *"Do you want the application 'cf-cli-java-plugin' to accept incoming network connections?"*
 > Click **Allow** — the plugin binds a temporary local server on `127.0.0.1` to serve the file
-> to the browser. The server shuts down automatically after the browser fetches the file once.
+> to the browser. The server serves only the exact one-time heap-dump URL generated for that download,
+> rejects alternate paths or query parameters, and shuts down automatically after one successful fetch.
 
 Getting a thread dump:
 
@@ -359,6 +371,22 @@ cf java thread-dump [my_app] -i [my_instance_index] > thread-dump.txt
 
 The `--keep` flag is not applicable to commands that stream output directly (e.g., `thread-dump`).
 
+Heap dumps support additional local post-processing and analysis options:
+
+- `--redact`: lean redaction mode; streams the heap dump through `hprof-redact` and zeros primitive arrays such as
+  `byte[]`, `char[]`, and similar bulk buffers
+- `--redact-complete`: complete redaction mode; streams the heap dump through `hprof-redact` and zeros primitive arrays
+  and individual primitive fields
+- `--redact-keep-on-error`: keeps a partially written redacted output file if local redaction fails; otherwise failed
+  redaction leaves no local heap dump behind
+- `--compress`: keeps the local output as `.hprof.gz` instead of transparently decompressing it
+- `--open`: starts a temporary local HTTP server on `127.0.0.1`, serves the downloaded heap dump once, and opens
+  [`hprof-analyzer`](https://parttimenerd.github.io/hprof-analyzer) automatically in your browser
+- `--open-url <URL>`: same as `--open`, but targets a custom hosted or self-managed `hprof-analyzer` instance
+
+These features can be combined, for example: `cf java heap-dump APP --redact --compress --open`.
+`--open` requires a local file and therefore cannot be used with `--no-download`.
+
 ### Heap Dump Privacy
 
 Heap dumps contain the full in-memory state of a JVM, including strings, byte arrays, and field values, which can
@@ -373,11 +401,14 @@ use `--redact` or `--redact-complete` to zero out sensitive values.
 Both modes preserve the full object graph (class names, references, instance counts), so the dump remains useful for
 memory analysis. The two flags are mutually exclusive.
 
-The redacted file is saved locally with a `-redacted` suffix; the original unredacted file is deleted automatically.
+The redacted file is saved to the requested local heap-dump path with no extra suffix. When redaction is enabled, the
+heap dump is streamed directly into `hprof-redact` exactly as downloaded, including gzip-compressed `.hprof.gz`
+streams, so the unredacted dump is never written to local disk.
 Use `--redact --compress` to also compress the output (produces a `.hprof.gz`).
 
-Redaction runs locally via the bundled [hprof-redact](https://github.com/parttimenerd/hprof-analyzer) binary after
-the dump is downloaded. Supported platforms: Linux (x86_64, arm64), macOS (Apple Silicon), Windows (x86_64, arm64).
+Redaction runs locally via the bundled [hprof-redact](https://github.com/parttimenerd/hprof-analyzer) binary while the
+dump is being downloaded. The binary is embedded from the
+[`hprof-analyzer`](https://github.com/parttimenerd/hprof-analyzer) project, so no separate installation is required.
 
 ### Compressed Transfer
 
@@ -391,6 +422,17 @@ Without `--compress`, the plugin still uses `gz=1` automatically when the remote
 compressed but the local file is transparently decompressed to a plain `.hprof`. This is the default behaviour
 starting from JDK 17 and costs nothing from the user's perspective.
 
+### Opening a Heap Dump in hprof-analyzer
+
+Use `--open` to inspect the downloaded heap dump immediately in
+[`hprof-analyzer`](https://github.com/parttimenerd/hprof-analyzer), either via the hosted instance at
+<https://parttimenerd.github.io/hprof-analyzer> or via your own deployment with `--open-url`.
+
+For safety, the plugin does **not** expose an arbitrary local directory. Instead, it starts a temporary local HTTP
+server bound to `127.0.0.1`, serves only the exact generated heap-dump for that one download, rejects alternate
+paths and query parameters, and shuts the server down automatically after one successful browser fetch or after a
+timeout if the browser never connects.
+
 ## Limitations
 
 Some commands depend on writable filesystem space inside the application container. In particular, `cf java heap-dump`,